A model-mediated harness for reliable agentic software development.
TeaQL Agent Kit demonstrates a new harness pattern for coding agents. Instead of letting an agent move directly from requirements to implementation, it places an executable domain model between intent and code.
The model becomes an inspectable intermediate representation. A deterministic evaluation service checks it and provides repair guidance. Generation turns the validated model into a typed API boundary, while model-aware assist teaches the agent the exact API available for the current domain.
The goal is not deterministic AI. It is deterministic structure around non-deterministic AI.
Correct-by-process, governed-by-runtime. TeaQL governs both how software is produced and how it behaves when it runs.
TeaQL applies constraints at two different times.
The Agent Kit controls how a coding agent moves from requirement to working software: model first, evaluate and repair, generate a typed contract, request current model-aware assist, implement within that contract, and verify the result with evidence.
The TeaQL runtime controls how the resulting application acts: operations carry identity and intent, reads declare purpose and comment, writes declare an audit reason, external capabilities are explicitly granted, and typed entity graphs constrain mutation.
Runtime governance does not choose the correct business policy. It makes application actions contextual, bounded, observable, and auditable once that policy has been chosen.
Most coding agents operate in a prompt-to-code loop:
requirement → agent → code → test → repair
TeaQL inserts a model-mediated control layer:
requirement
↓
inspectable domain model
↓
deterministic evaluation and repair
↓
generated typed contract
↓
constrained agent implementation
↓
compile, test, runtime, and audit evidence
This changes the role of the agent. The agent no longer invents the domain contract, persistence surface, and business logic at the same time. It models intent first, works against a generated contract, and demonstrates completion with concrete evidence.
TeaQL Agent Kit is therefore not merely a code-generation Skill. It is a reference implementation of a model-mediated harness for coding agents.
flowchart TD
R["Business requirement"] --> A["Coding agent"]
A --> M["Inspectable KSML model"]
M --> E["Deterministic evaluation"]
E -->|"Errors and repair guidance"| A
E -->|"Validated model"| G["Generated typed contract"]
G --> I["Constrained implementation"]
G --> H["Model-aware assist"]
H --> A
I --> V["Compile, test, runtime, and policy checks"]
V -->|"Implementation defect"| A
V -->|"Model defect"| M
V --> O["Evidence-backed result"]
U["Human reviewer"] -. "Asynchronous feedback" .-> M
U -. "Asynchronous feedback" .-> I
The harness has five cooperating parts:
- Inspectable intermediate representation — KSML turns business intent into a saved artifact that agents, tools, and people can inspect and revise.
- Deterministic feedback oracle — model evaluation returns errors, warnings, suggestions, and current repair guidance instead of relying on the agent to memorize a large rule catalog.
- Generated action boundary — typed domain APIs and model-aware assist narrow the implementation surface and reduce API invention.
- Policy-bearing APIs — identity context, query purpose, query comments, and write audits travel with execution rather than remaining prompt advice.
- Evidence-based completion — evaluation, generated guidance, policy checks, compilation, tests, and runtime results form a traceable evidence chain from requirement to application.
These constraints do not make an agent infallible. They make its actions smaller, more observable, and easier to review.
The repository publishes the harness as a focused Agent Skill:
SKILL.mddefines the mandatory model-first execution order and agent constraints.golden-example.xmlprovides a compact grammar example without loading a full rule catalog.toolchains.mdbinds the workflow to versioned clients, evaluation, generation, and model-aware assist.work-complete.mddefines the evidence required before the agent reports completion.
Together, these artifacts coordinate the agent, the model evaluator, generated contracts, runtime policies, verification tools, and parallel human review.
The live Generation Service presents the same model-mediated path as a guided, five-stage walkthrough:
Walk through the live TeaQL harness
- Turn a business requirement into a saved KSML domain contract.
- Inspect the model as an interactive entity graph or data dictionary.
- Evaluate the model, repair reported Errors, and retain the report as evidence.
- Generate stable domain libraries and separate editable application workspaces and libraries for Java, Rust, Go, Swift, Python, C#/.NET, or TypeScript.
- Develop against the generated contract with model-, language-, action-, and object-specific assist.
The page also exposes a live evaluation report, generation target catalog, workspace API guides, and language-specific previews and assist for create, update, query, list, expression, delete, debugging, granted tool API, and runtime customization guidance. Preview depth can vary by language; the current target catalog and generated assist are authoritative.
This live surface demonstrates that the evaluator, generators, typed
contracts, and just-in-time assist are concrete parts of the harness rather
than conventions described only in a prompt. The /latest/ endpoint follows
the current published demo and may evolve with the service.
Install the complete model-to-application workflow with the community Skills CLI:
npx skills add teaql/teaql-agent-kit --skill build-teaql-appThen ask your coding agent:
Use $build-teaql-app to first draft and save a complete KSML model, then
evaluate and repair it before generating a runnable TeaQL application: ...
This repository can publish multiple focused Skills. build-teaql-app is the
end-to-end workflow: model, evaluate, generate, implement, verify, and report.
A compact KSML model describes business objects, fields, constants, relationships, modules, and storage:
<root cfg_mask_china_mobile="false"
data_service="sqlite"
name="bookstore-service"
org="example"
_module_key="root">
<bookstore _name="Bookstore"
_module="Organization"
_module_key="organization"
name="TeaQL Books"/>
<book _name="Book"
_module="Catalog"
_module_key="catalog"
title="Domain Modeling with TeaQL"
bookstore="bookstore()"/>
</root>The Generation Service turns the validated model into entities, relation metadata, typed queries, null-safe expressions, graph persistence, checker and behavior hooks, repository registration, documentation, and a runnable application workspace.
Application code then reads in domain language rather than generic ORM plumbing:
let merchants = Q::merchants()
.select_name()
.which_names_contain("tea")
.purpose("Find merchants for search results")
.comment("Search merchant names")
.execute_for_list(&ctx)
.await?;The generated domain library is a model-derived contract and remains regenerable. Business logic stays in a separate editable application workspace.
After modeling and evaluation, the agent sends a compact signal:
Model Ready
- Model: /path/to/project/models/model.xml
- Evaluation: passed — 0 errors, 2 warnings, 1 suggestion
The path lets a person open and review the actual model. The notification does not stop execution: the agent continues generating, implementing, testing, and repairing the application.
Human review happens alongside that work. A reviewer can inspect the model or running application at any time and send feedback asynchronously. If feedback changes the domain contract, the agent updates the model, evaluates it again, regenerates, and continues.
sequenceDiagram
participant A as "Coding agent"
participant U as "User / reviewer"
A->>A: Model and evaluate
A-->>U: Model path + evaluation result
par Agent continues
A->>A: Generate, implement, and test
and Human reviews
U->>U: Review model or application
U-->>A: Send asynchronous feedback
end
A->>A: Incorporate feedback and continue
Review is a parallel activity, not a waiting node.
TeaQL constrains how agents interact with business data:
- Mandatory identity — operations pass through
UserContext, making identity and request scope explicit. - Intent auditing — reads declare their purpose and comment; writes carry an audit description.
- Capability sandbox — HTTP, file access, messaging, and similar tools are explicitly granted rather than ambient.
- Graph mutability control — typed entity graphs replace manually coordinated SQL updates and relationship loops.
- Semantic error translation — infrastructure failures can become stable, actionable application errors.
The Agent Kit defines the shared harness pattern. Runnable applications remain in language-specific repositories so their toolchains, dependencies, and release cycles can evolve independently:
| Example | Application surface | Harness behavior demonstrated |
|---|---|---|
| Java Robot Task Board | Local Android application | Model-derived typed CRUD, query purpose and comment, audited writes, and visible SQL execution logs |
| Java Vending Machine Desktop | Compose Desktop and SQLite | A generated domain library embedded in a local desktop application |
| Java World Cup CLI | Interactive CLI and SQLite | Declarative domain modeling, generated query and entity APIs, relational queries, and audited persistence |
| Java Vending Machine | Spring Boot, Quarkus, and Micronaut | One modeled domain hosted across multiple Java application frameworks |
| Rust World Cup CLI and TUI | Interactive CLI, TUI, and SQLite | Model-to-generated-library separation, typed Q and E APIs, and audited graph persistence |
| Rust Linux System Info | Linux /proc provider and console UI |
A generated typed query boundary applied to an operating-system capability rather than a conventional database |
These examples provide runnable application and code evidence. An end-to-end recording can complement them with agent-execution evidence: the initial model, evaluation and repair rounds, generated assist, policy checks, compilation, tests, and runtime results.
TeaQL natively supports seven major languages. While the core philosophy remains identical, the implementation maturity of specific features varies by ecosystem.
Legend:
- 🟢 Supported: Feature is implemented and working.
- 🟡 Partial / WIP: Feature is partially implemented or under active development.
- ⚪ Not Supported: Feature is not yet implemented or not applicable for this language tier.
This snapshot records generated-code and real-runtime evidence, not only the presence of an adapter or a code template. A green database entry means the generated API chain compiled and ran against that database with real persistence. Some results are on validated development branches, so merge and release availability can lag behind this engineering snapshot.
| Language runtime | Latest verified runtime evidence | Verified databases | Qualification |
|---|---|---|---|
| Java | Full database matrix: 9 tests / 0 failures / 0 errors / 0 skipped |
PostgreSQL, MySQL, SQLite, Oracle, DB2, DM8, SAP HANA, SQL Server, DuckDB | Broadest enterprise database coverage; Android remains SQLite-only |
| Rust | Generated API chain and runtime suite passed; runtime branch coverage reached 95.5% | PostgreSQL, MySQL, SQLite | SQL Server is intentionally out of scope |
| Go | Runtime suite and generated SQL matrix passed; statement coverage reached 94.9% | PostgreSQL, MySQL, SQLite | Includes generated-query WithComment compatibility |
| Swift | Generated Swift package and runtime suite pass on the current conformance baseline | SQLite | Local-first runtime for iOS/macOS plus a TFP federation client; no federation server |
| Python | 73 runtime tests passed plus generated real-SQL integration |
PostgreSQL, MySQL, SQLite | Uses real async SQL providers; no longer counted as JSON/fake persistence |
| C# / .NET | 124 runtime tests passed plus generated database integration |
PostgreSQL, MySQL, SQLite, SQL Server | SQL Server support is specific to Java and .NET |
| TypeScript | 6 runtime tests plus 4 tests / 0 failures / 0 errors / 0 skipped generated matrix |
PostgreSQL, MySQL, SQLite | Canonical Node SQL runtime; the browser/TFP entry installs and loads no database driver |
| Feature Area | Java | Rust | Go | Swift | Python | C# (.NET) | TypeScript |
|---|---|---|---|---|---|---|---|
| Core Runtime | |||||||
| AST Parsing & Query Execution | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Audited Graph Persistence | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| UserContext & Identity | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Triple-Intent Policy | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Data Providers | |||||||
| SQLite | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| MySQL | 🟢 | 🟢 | 🟢 | ⚪ | 🟢 | 🟢 | 🟢 |
| PostgreSQL | 🟢 | 🟢 | 🟢 | ⚪ | 🟢 | 🟢 | 🟢 |
| MS SQL Server | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | 🟢 | ⚪ |
| Oracle | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ |
| DB2 | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ |
| SAP HANA | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ |
| DuckDB | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ |
| DM8 (Dameng) | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ |
| Snowflake | 🟡 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ |
| Advanced Integrations | |||||||
| Federation Protocol (TFP) Server | 🟢 | 🟢 | 🟢 | ⚪ | ⚪ | 🟢 | ⚪ |
| TFP HTTP Provider (Client) | ⚪ | ⚪ | ⚪ | 🟢 | 🟢 | ⚪ | 🟢 |
| Web Framework Integration | 🟢 | 🟢 | 🟢 | ⚪ | 🟢 | 🟢 | ⚪ |
| Redis Cache | 🟢 | 🟢 | 🟢 | ⚪ | 🟢 | 🟢 | ⚪ |
| Cloud Native (Microservices) | |||||||
| Nacos Integration | 🟢 | 🟢 | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ |
| Consul Integration | 🟢 | 🟢 | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ |
| Health Actuator & Metrics | 🟢 | 🟢 | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ |
| Tooling & Code Generation | |||||||
| Typed DSL Generation | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| Dynamic String Interpreter | 🟢 | ⚪ | ⚪ | ⚪ | ⚪ | ⚪ | 🟢 |
💡 Note on Java Database Support: The Java ecosystem has highly adaptable data provider support depending on its execution environment:
- Server / Backend (Spring Boot, Quarkus, etc.): The latest full-chain matrix verifies PostgreSQL, MySQL, SQLite, Oracle, DB2, DM8, SAP HANA, SQL Server, and DuckDB. Snowflake is not counted as verified because no official locally runnable Snowflake database service image was found.
- Android / Mobile (
teaql-android): When running natively on mobile, database support is strictly constrained to SQLite to ensure local compatibility, zero-configuration, and memory efficiency without pulling in heavy JDBC drivers.
💡 Note on TypeScript Profiles: The green SQL entries apply to the explicit Node.js profiles
teaql-ts/sql/postgres,teaql-ts/sql/mysql, andteaql-ts/sql/sqlite. The defaultteaql-tsbrowser/TFP entry has no SQL import and does not install or loadpg,mysql2, orbetter-sqlite3.
The Generation Service provides the most complete model-derived output set:
- Java, Rust, Go, Swift, Python, C#/.NET, and TypeScript typed domain libraries
- Editable application workspaces
- Model evaluation and repair guidance
- Object-specific query, create, update, delete, and expression assist
Kotlin/JVM application code is supported through the generated Java library and TeaQL Java runtime, as demonstrated by the Compose Desktop vending-machine example. It is application-language interoperability, not a separate eighth runtime or generation target.
Swift is a current swift-lib-core generation target with a local-first SQLite
runtime for iOS and macOS and a TFP client. It does not currently provide a
Swift TFP server or a separate editable application-workspace target. C++,
Dart, Ruby, and other unlisted smaller language ecosystems are not currently
supported.
- Runtime and tool guides generated for the current domain
- Data-design, model-view, and frontend model outputs
Developers who want to inspect or extend an open-source generation service written in Rust can explore teaql-forge-rs. Forge is a small open implementation and does not claim full feature parity with the TeaQL Generation Service.
TeaQL Agent Kit is available under the MIT License.