Charter: kawa
Generated from docs/ai/charters/kawa.md. Edit that file, then regenerate: python docs/portfolio/_build/generate_reference_pages.py.
Status: Certified — passes all seven mandatory rows (2026-08-09) Runtime: kavai.systems.kawa.runtime · Backend: kawa adapter (:8082) Legacy alias: hermes resolves to the same module
Job
Answer an integrity engineer’s question by using tools — querying the database, reading a document, walking an IOW workflow — rather than by generating SQL from the question in one shot.
Users
Integrity engineers in the Integrity workspace, and anyone driving the assistant through the AG-UI chat surface. It is the engine behind the API 584 IOW workflow.
In scope
- Tool-using investigation: multi-step questions where the answer requires looking something up, then looking something else up based on the first result.
- The API 584 IOW workflow.
- The rendered surfaces the contract defines — dataset lists, image galleries, markdown reports.
Out of scope
- Bulk NL-to-SQL analytics. That is the ADK track’s shape (
argus,orion), and routing isSYSTEM_TO_BACKEND’s job, not a runtime decision. - Image analysis it has not been given a skill for. Surface analysis is a declared capability row; kawa passes it, but a request outside its registered skills is declined rather than approximated.
- Anything requiring data the caller cannot see. Not “filtered” — declined.
Must never
| Constraint | Enforced by |
|---|---|
| Answer over data outside the caller’s scope | scope row (FR-AI-08, mandatory) — pass — plus RLS under CONTRACT-API-001 |
| Serve an unauthenticated caller | auth-failure row (mandatory) — pass |
| Emit a signed URL, storage path, or credential | CONTRACT-CDC-001 §7.4.1 + image-browsing row — pass |
| Emit an event shape the contract does not define | CONTRACT-CDC-001, lint-enforced |
| Leave test residue in a real dataset | test-data-hygiene row (mandatory) — pass |
| Present model output as a recorded finding | nothing — intent only. The suggestion/annotation boundary is enforced in the web surface (annotation_suggestions, 20260809_ai_annotation_suggestions.md D1), not in the engine. An engine that phrased a suggestion as a finding would not fail any current row |
| Answer from a document it did not read | nothing — intent only. KAB’s non-answerable half punishes guessing on questions with no answer; it does not catch a confident answer sourced from the wrong place |
Certification
Declares no capability rows of its own; passes surface-analysis anyway.
Current result (ENGINE_CERTIFICATION.md, certified 2026-08-09, feature-suite revision f18116dc):
| Row | Mandatory | kawa |
|---|---|---|
dataset-discovery |
yes | pass |
image-browsing |
yes | pass |
surface-analysis |
if-declared | pass |
report-answers |
yes | pass |
lifecycle |
yes | pass |
auth-failure |
yes | pass |
scope |
yes | pass |
test-data-hygiene |
yes | pass |
provenance |
no | skip |
Gated by: ai/tests/features (pixi run certify-engines) and the KAB suite (docs/evaluation/benchmark/).
Operational note
kawa runs as a standalone adapter on :8082, not in the ADK runtime — the in-process kawa system needs that adapter reachable or the gateway has no address to call. Local development quirks are in docs/handbooks/content/ai/runtime-and-systems.md; this charter governs behaviour, not deployment.