From 0dde27da235266ae403ff4d9ebfe5aa984a59d72 Mon Sep 17 00:00:00 2001 From: Philip Z Date: Sat, 10 Oct 2026 21:22:40 +0800 Subject: [PATCH 1/2] docs: explain AI-native libraries and reviewable business code Signed-off-by: Philip Z --- README.md | 224 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 167 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 4603df3..eee7d6a 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,68 @@ # TeaQL Python -Review the business operation, not pages of persistence plumbing. +An AI-native library and runtime for building reviewable business applications in Python. -TeaQL Python 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. +[Try with your coding agent](#try-it-with-your-coding-agent) · +[Run the local example](#run-the-local-example) -## 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 Python 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 | +| Intent and execution evidence | Query diagnostics and mutation audit delivery | -Python 3.10+; Python 3.12+ is recommended. Async SQL execution uses the selected provider driver. 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 -python -m venv .venv -. .venv/bin/activate -python -m pip install -e . -export PYTHONPATH="$PWD/src" -(cd examples/school-management && python -m app.main) -``` +**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 Python 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 @@ -61,10 +70,13 @@ domain library, not a generic runtime object with arbitrary field strings. See the [application source](examples/school-management/app/main.py) for complete setup. ```python +def school_type_details(): + return Q.school_types_minimal().select_name().select_code() + school = await ( Q.schools().with_id_is(school_id) .select_platform_with(Q.platforms_minimal().select_name().select_base_url()) - .select_school_type_with(Q.school_types_minimal().select_name().select_code()) + .select_school_type_with(school_type_details()) .comment("what: load the school and its reference data") .purpose("why: review a school before editing") .execute_for_one(context) @@ -73,20 +85,32 @@ if school is None: raise ValueError("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 ```python type_code = E.school(school).school_type().code().eval() ``` -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 @@ -104,25 +128,31 @@ 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 +## Execution evidence helps the next development step + +Logs are useful development context, not just an operations feature. They +help an agent and a reviewer connect the requested behavior with what ran, +and help an operator investigate a production change. 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 @@ -131,6 +161,86 @@ 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 Python query path is: + +```bash +cargo teaql python-assist-query/school --input models/ +cargo teaql python-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 | + +Python annotations describe the API but are not a Rust-style compile-time +guarantee. Runtime checks and tests must 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 Python 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 + +Python 3.10+; Python 3.12+ is recommended. Async SQL execution uses the selected provider driver. From a checkout of this repository: + +```bash +python -m venv .venv +. .venv/bin/activate +python -m pip install -e . +export PYTHONPATH="$PWD/src" +(cd examples/school-management && python -m app.main) +``` + +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: **0.3.0**. Keep domain-library and runtime From ccb452c865f00df36b263bb38fd10e18aaa1a9b0 Mon Sep 17 00:00:00 2001 From: Philip Z Date: Sat, 10 Oct 2026 23:04:36 +0800 Subject: [PATCH 2/2] docs: highlight automatic logs for debugging and operations Signed-off-by: Philip Z --- README.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index eee7d6a..3997cc2 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,12 @@ 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. +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) +[Run the local example](#run-the-local-example) · +[See automatic logs](#automatic-logs-without-handwritten-logging-code) ## Why this is an AI native library @@ -38,7 +42,7 @@ and runtime. | 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 | -| Intent and execution evidence | Query diagnostics and mutation audit delivery | +| Business intent and audit reason | Automatic execution logs and trace context without per-operation logging code | Reviewers still decide whether the requested data, business rules and authorization policy are correct. They have less application plumbing to @@ -128,11 +132,31 @@ 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. -## Execution evidence helps the next development step +## 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. +- `audit_as` 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. -Logs are useful development context, not just an operations feature. They -help an agent and a reviewer connect the requested behavior with what ran, -and help an operator investigate a production change. +- **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.