Start from an Example

The most direct first evaluation is to give an AI coding agent one small domain and require it to prove the complete model-to-build loop.

This path uses the TeaQL Agent Kit because the exact generation and build commands depend on the selected stack, client version, and generated workspace. The agent must inspect those inputs; it must not guess commands or generated method names.

Expected Outcome

At the end of this exercise you should have:

• a reviewed TeaQL semantic model;
• generated source or a generated workspace;
• a successful build or test result;
• one located generated entity and Q request API;
• a record of the commands used;
• no manual edits inside generated output.

Before selecting an example, check the Examples and Evidence Index. It distinguishes current executable fixtures from Model Explorer illustrations and historical reports whose TeaQL/client versions are no longer current.

Completion time depends on whether the required Java/Rust toolchain and TeaQL client are already installed. Treat the first run as an evaluation with evidence, not as a timed demonstration.

Before You Start

You need:

• a coding agent that can inspect files and run local commands;
• Git;
• the toolchain required by the selected target stack;
• access to the TeaQL client used by the Agent Kit.

The built-in TeaQL client credentials are sufficient for the standard workflow; do not stop to search for an additional API key.

Give the Agent a Bounded Task

For a Java evaluation, use this prompt:

Follow the current instructions from https://github.com/teaql/teaql-agent-kit.

Use Java to build a small school management example with these concepts:

- Platform
- School
- School Type, with values Primary and Secondary

Work in this order:

1. Create the TeaQL semantic model.
2. Show the model for review before generation.
3. Evaluate the model and read the complete Markdown report if evaluation fails.
4. Generate the Java library and runnable application using the commands defined by the current Agent Kit and client.
5. Do not edit generated source files.
6. Build or test the generated workspace.
7. Locate the generated School entity and request API and report their exact method names.
8. Report every command used, its working directory, and the final verification result.

For Rust, replace the target instruction with:

Use Rust as the generated target. Before generation, run the installed TeaQL
client's help and evaluation commands. Use dependency versions emitted by the
current generator or workspace template. Build or test the generated workspace
and locate the generated School entity and Q request API.

Review the Model Gate

Do not approve generation until the model demonstrates:

• business names rather than table-oriented names;
• an explicit relationship between the platform and schools;
• a concrete representation for the school type values;
• no empty attributes;
• no unnecessary nested references;
• a clear root and ownership choice where the model requires one.

For a serious project, read the complete project modeling rules before approving structural decisions. The quick example is intentionally small; it is not a template for every tenancy or aggregate design.

Require Evaluation Before Generation

The Rust client exposes this workflow through commands such as:

cargo teaql --help
cargo teaql services
cargo teaql evaluate --input model/main.xml

With cargo-teaql 2.0.8, generate Rust targets explicitly rather than using a generic generate word:

cargo teaql rust-lib-core --input model/main.xml --output generated/rust-lib-core
cargo teaql rust-app-console --input model/main.xml --output generated/rust-app-console

Keep these output directories as siblings: the current console manifest refers to ../rust-lib-core/lib.

A Maven-based Java project that already declares the TeaQL plugin can inspect it with:

mvn teaql:help

For standalone inspection of the locally verified plugin version, use the full coordinate:

mvn io.teaql:teaql-maven-plugin:1.1.0:help -Ddetail=true
mvn io.teaql:teaql-maven-plugin:1.1.0:list-services

Use the installed client's output as the authority for supported flags and goals. TeaQL Maven plugin 1.1.0 evaluates with eval and generates through a single dynamic goal:

mvn io.teaql:teaql-maven-plugin:1.1.0:eval -Dinput=model
mvn io.teaql:teaql-maven-plugin:1.1.0:generate \
  -Dservice=java-app-console \
  -Dinput=model

Select service from the current list-services output. If evaluation or generation produces a Markdown validation report, read it before making any fix, then correct the model or configuration and rerun the same goal.

Inspect the Generated Boundary

After generation, ask the agent to classify files into three groups:

Group	Expected treatment
Model and generator configuration	Source inputs; edit these to change generated contracts.
Generated source or workspace	Derived output; inspect it, but do not use it as a handwritten patch surface.
Application and extension code	Handwritten behavior that uses documented generated APIs and extension points.

The exact directories vary by generator and workspace version. Record the paths produced by the current run instead of copying directory assumptions from an older example.

Verify the Build

Use the wrapper or build command included in the generated workspace. A report that files were generated is not sufficient.

Capture:

• the command and working directory;
• the client, runtime, and toolchain versions visible in the workspace;
• the successful build or test result;
• the generated School entity path;
• the generated request API path and exact query method names.

If compilation fails because a method does not exist, read the generated source. Do not add the guessed method to a generated file.

Run or Prepare the First Query

The application should use the generated API and declare query intent. The exact entity pluralization and filter methods must come from generated source. A Java request follows this shape:

Q.schools()
    .comment("Query schools")
    .purpose("Review the generated school list")
    .executeForList(ctx);

A Rust request follows this shape:

Q::schools()
    .comment("Query schools")
    .purpose("Review the generated school list")
    .execute_for_list(&ctx)
    .await?;

These are API shapes, not permission to assume that the generated entry point is named schools. Confirm the actual name in the generated request facade.

Completion Checklist

• The model was reviewed before generation.
• Evaluation passed, or every reported violation was resolved in the model or configuration.
• Generation used commands supported by the installed client.
• The generated workspace built or passed its relevant tests.
• Generated entity and request source paths were recorded.
• Exact generated method names were inspected rather than guessed.
• No generated source was manually patched.
• Query examples include both operation comment and business purpose.
• The command log and verification evidence are available for review.

Continue the Evaluation

Make one small field change and follow Regenerate and Review. If any stage fails, use Troubleshoot First Run.