Skip to content

docs: explain AI-native libraries and automatic execution logs #207

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
philipgreat merged 2 commits into from
Oct 10, 2026
Merged

docs: explain AI-native libraries and automatic execution logs #207

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd34718
docs: explain AI-native libraries and reviewable business code
Oct 10, 2026
ac801a7
docs: highlight automatic logs for debugging and operations
Oct 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 185 additions & 53 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,89 +1,120 @@
# TeaQL Java

Review the business operation, not pages of persistence plumbing.
An AI-native library and runtime for building reviewable business applications in Java.

TeaQL Java is a reusable, domain-independent runtime for model-aware applications.
A generated domain library gives your application language-native **Q** queries,
**E** expressions and governed graph mutations. The runtime executes them
through metadata, Context, Checker, Policy and provider boundaries.
TeaQL gives coding agents business-shaped APIs, model-aware guidance and
software checks. People review the business operation instead of reconstructing
pages of query-building, relationship-loading and persistence code.

The goal is to let people and coding agents express—and review—business intent
in a small amount of application code.
Automatic execution logs make those operations easier to debug and operate,
without adding logging statements to every business method.

[Try with your coding agent](#try-it-with-your-coding-agent) ·
[Run the local example](#run-the-local-example) ·
[See automatic logs](#automatic-logs-without-handwritten-logging-code)

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13612/badge)](https://www.bestpractices.dev/projects/13612)

## What you gain
## Why this is an AI native library

| Capability | Benefit to application developers |
| --- | --- |
| Composable Q API | Combine filters, projections and relation requests without duplicating relationship-loading code; review what is being requested. |
| Safe E API | Distinguish an unloaded field from a loaded NULL; do not mistake an incomplete result for a business fact. |
| Governed graph Save | Stage creates, updates and deletions, then validate and persist through one Save boundary rather than hand-written SQL loops. |
| Execution and audit evidence | Follow declared intent, SQL routes and mutation responsibility when debugging or explaining a change. |
AI-native does not mean the library was written by AI, or that every query
calls an LLM. It means the APIs, knowledge delivery and verification workflow
are designed for how coding agents work: limited context, incomplete knowledge
of a project and a tendency to guess unfamiliar operations.

## Try it with your coding agent
The semantic model describes your business objects, fields, relationships and
states. A generated domain library turns those words into language-native
**Q** queries, **E** expressions and mutation methods. This repository provides
the reusable, domain-independent **runtime** that executes them through
metadata, Context, Checker, Policy and database providers.

You can start with an agent you already use. Paste this prompt:
The application workspace keeps business code and concise project guidance
together. Progressive **Assist** supplies the exact API guidance needed for
the next operation, instead of asking the agent to explore the entire generated
library. Compilation, runtime checks and tests provide feedback beyond a prompt.

```text
Follow the current instructions at https://github.com/teaql/teaql-agent-kit.
Build a small school-management application in Java using SQLite.
Evaluate and repair the model, generate the library and workspace, then verify
Q, E, Checker and audited Save. Report commands, results and remaining frictions.
```
## Less code for a reviewer to reconstruct

The [Agent Kit](https://github.com/teaql/teaql-agent-kit) guides modeling,
evaluation/repair, generation and application customization. It may install
toolchains and download dependencies; review installation permissions and the
final execution report. It is a workflow, not a guarantee of unattended correctness.
The benefit is visible in the application code: the query, data access path
and audited change stay together, while shared mechanics live in the library
and runtime.

## Run the local example
| Application code to review | Shared work handled by TeaQL |
| --- | --- |
| A composed Q request | SQL construction and selected relation loading |
| An E access path | Loaded-field checks and explicit NULL handling |
| A mutation with an audit reason | Change tracking, Checker and configured Policy execution |
| Business intent and audit reason | Automatic execution logs and trace context without per-operation logging code |

Java 17+ and Maven 3.8+. From a checkout of this repository:
Reviewers still decide whether the requested data, business rules and
authorization policy are correct. They have less application plumbing to
trace before making that decision; reuse does not make business logic correct
automatically.

```bash
bash examples/verify-runtime-examples.sh
```
**Token savings have not yet been measured in a controlled comparison.**
We make no numerical token-saving claim. Loading guidance only when needed
is a context-management strategy; the smaller application review surface is
visible in the examples, not a measured percentage reduction in review time.

The [School example](examples/school-management/README.md)
exercises SQLite schema/bootstrap and generated application APIs against this
repository's local runtime. No external database server or generator is needed
to run the retained generated example. Use only the example's test database;
reset/repeated-run behavior is documented in its README.
## See a business operation execute

The [Robot Task Board showcase](https://teaql.io/blog/robot-task-board-showcase/)
makes the idea concrete: move a task and follow the state change, generated
SQL, field-level audit and refreshed board.

![TeaQL Robot Task Board](https://teaql.io/img/003-task-board.png)

## Query and read the result
Explore the [open-source demo](https://github.com/teaql/robot-task-board).
The showcase is a Rust application; the examples below use this repository's
own Java APIs.

## Q API composes business queries

These application-code excerpts assume the example's generated imports, trusted
Context and an existing object identity. `Q` and `E` belong to the generated
domain library, not a generic runtime object with arbitrary field strings.
See the [application source](examples/school-management/src/main/java/com/example/schoolmanagementservice/SchoolLifecycleVerifier.java) for complete setup.

```java
var schoolTypeDetails = Q.schoolTypesWithMinimalFields().selectCode();

School school = Q.schools()
.withIdIs(schoolId)
.selectPlatformWith(Q.platformsWithMinimalFields().selectName())
.selectSchoolTypeWith(Q.schoolTypesWithMinimalFields().selectCode())
.selectSchoolTypeWith(schoolTypeDetails)
.comment("what: load the school and its reference data")
.purpose("why: review a school before editing")
.executeForOne(context);
if (school == null) throw new IllegalStateException("School not found");
```

The selected relation request is another typed query: it can be composed and
reused independently. `comment` describes **what**; `purpose` describes **why**.
Both must be non-empty, even when logging is disabled.
The child request is a query in its own right. Give it a business name,
extract it into a helper and compose it into other requests like a Lego brick.
The reviewer can see which relationships are loaded without following a
separate set of SQL loops. `comment` describes **what**; `purpose` describes
**why**. Both must be non-empty, even when logging is disabled.

## E API protects business reads

```java
String name = E.school(school).getName().eval();
String typeCode = E.school(school).getSchoolType().eval().getCode();
```

E reads the loaded graph without implicitly querying the database. Unloaded
modeled fields remain guarded, rather than silently becoming NULL. The exact
error/result representation follows the language's API. A NULL fallback is
not permission to ignore an unloaded property.
E reads the loaded graph without implicitly querying the database. A loaded
NULL and a field that was **NotLoaded** are different facts. A business rule
must not conclude that a value is absent merely because the query never
requested it.

The access path is explicit, so the reviewer checks whether Q loaded the
required data and whether the code handles a real NULL appropriately.
Unloaded access produces the language-specific diagnostic; a NULL fallback
is not permission to ignore an unloaded property.

## Mutation API keeps changes behind one Save boundary

## Change the object and save
The application declares the change and its reason instead of writing its own
persistence loop. A graph can stage additions, updates and deletions before Save.

Load the complete scalar fields of every persisted object you actually modify.
A display-only partial projection is not a complete mutation input. Unmodified
Expand All @@ -104,25 +135,51 @@ approval emits a warning; it is not automatic rejection. Marking for deletion
stages a change—the audited Save performs it. Atomicity is provider/route scoped,
not a distributed transaction across unrelated databases.

## See why an operation happened
## Automatic logs without handwritten logging code

**Debuggability and operability are core design goals.** The Q and Save
examples above contain no logging calls: you declare the business intent,
and the runtime produces the execution diagnostics and trace context.
Configured audit sinks receive change events without each application
method having to construct its own field-level diff.

The intent declarations already belong to the business operation:

- `comment` describes what the query does.
- `purpose` explains why it runs.
- `auditAs` gives the reason for a saved change.

No-code logging means no handwritten logger calls in each business method,
not an application without code or intent declarations. Runtime startup
still configures any required sink; custom formats and destinations use the
logging extension points rather than edits to every business operation.

- **Debugging:** connect a query's intent to generated SQL, execution outcome
and the trace path when a screen or business operation behaves unexpectedly.
- **Operations:** follow query and mutation activity and use audit reasons
and safely exposed changes to investigate incidents.
- **Review:** inspect the business operation without separately checking
that every TeaQL execution path has a matching application logging statement.

Query and Mutation diagnostic logs are enabled by default and can be switched
off independently. Logging off does not disable intent validation or Policy.

Intent, physical SQL paths and mutation responsibility are separate facts.
For example, a safe diagnostic can tell an operator which query populated a
screen, and an audit can explain why a saved object changed.

Illustrative, shortened view—not a literal logger format or a benchmark result:
Illustrative, shortened view of the rename operation, not a literal logger
format or a captured test result; the SQL excerpt omits additional selected fields:

```text
query entity=School comment="load the reviewed object" purpose="edit form" outcome=success
SQL: SELECT id, version FROM school_data WHERE id = 42;
SQL: SELECT id, version, name FROM school_data WHERE id = 42;
trace: School -> request -> sqlite -> select
mutation entity=School auditReason="Rename the reviewed school" outcome=committed
change: name "Riverside Primary School" -> "Riverside Academy"
lineage: School#42("Rename the reviewed school")
```

The declarations explain **why**; SQL and audit evidence show **what happened**.
Together they help locate the relevant operation without reconstructing the
entire call path from scattered application code.

SQL execution stays parameterized. Diagnostic SQL has parameters substituted
after field-aware masking; it is not a question-mark template you must manually
reconstruct. Ordinary bindings stay visible, sensitive bindings use the shared
Expand All @@ -131,6 +188,81 @@ is labeled `MASKED; NOT REPLAYABLE`; SQL that cannot be safely rendered is omitt
Application mutation audits are delivered after commit and discarded on rollback.
This is not a durable audit outbox. Do not put secrets in comment or purpose.

## Discover only the API needed next

A coding agent does not need every generated method in its context. Start with
the generated application's `AGENTS.md` and workspace guidance, request an
entity/action Assist, then ask for field-specific help only for the field
being used.

For a model in `models/`, the Java query path is:

```bash
cargo teaql java-assist-query/school --input models/
cargo teaql java-assist-query/school.established_date --input models/
```

These commands call the model-aware service; the model must match the generated
library. Assist uses canonical KSML entity and field names, even when the
language-native API uses a different naming style. Cargo TeaQL is a service
client for multiple languages, not just Rust.

Use Assist to discover operations instead of reading generated library source
or guessing names. If the required operation is missing, report
`MISSING_ASSIST` rather than inventing an API. The
[Agent Kit](https://github.com/teaql/teaql-agent-kit) defines this progressive
workflow. Library and runtime maintenance are separate from application coding.

## Software checks complement agent instructions

AI proposes the model and application logic; software checks the parts that
can be verified mechanically. The library is one part of the TeaQL harness,
not a replacement for business review.

| Stage | TeaQL support | Feedback to inspect |
| --- | --- | --- |
| Model and repair | Semantic model evaluation | Errors, warnings and repair guidance |
| Generate | Domain library combined with this runtime | Language tooling checks the generated API contract |
| Customize the workspace | Progressive Assist, Q, E and mutation APIs | Build diagnostics, Checker and configured Policy results |
| Verify and operate | Tests, runtime startup, intent and audit evidence | Actual outcomes, remaining failures and execution paths |

Build checks verify API use, not whether the business decision is right.
Tests must still verify the application's behavior. A prompt, successful
generation or a clean build alone does not prove the finished application correct.

## Try it with your coding agent

You can start with an agent you already use. Paste this prompt:

```text
Follow the current instructions at https://github.com/teaql/teaql-agent-kit.
Build a small school-management application in Java using SQLite.
Evaluate and repair the model, generate the domain library and prepare a runnable
application workspace. Verify Q, E, Checker and audited Save.
Finish with a report of commands, results and
remaining frictions. Include Q/E examples and relevant intent/audit logs.
Do not claim token savings without a measured comparison.
```

The [Agent Kit](https://github.com/teaql/teaql-agent-kit) guides modeling,
evaluation/repair, generation and application customization. It may install
toolchains and download dependencies; review installation permissions and the
final execution report. It is a workflow, not a guarantee of unattended correctness.

## Run the local example

Java 17+ and Maven 3.8+. From a checkout of this repository:

```bash
bash examples/verify-runtime-examples.sh
```

The [School example](examples/school-management/README.md)
exercises SQLite schema/bootstrap and generated application APIs against this
repository's local runtime. No external database server or generator is needed
to run the retained generated example. Use only the example's test database;
reset/repeated-run behavior is documented in its README.

## Use the published runtime

Current documented runtime: **1.554-RELEASE**. Keep domain-library and runtime
Expand Down
Loading