Build an offline ambient quality worker with Python

Start with evidence behavior you can inspect

A small deterministic worker is useful because every result can be traced to a rule and a fixture. The companion example examines synthetic records containing a failed tool request, an unsupported completion claim, a successful event, and injected text. It exercises evidence checks and produces findings without modifying an external system. It is intentionally narrower than a model-based investigator: it cannot interpret arbitrary customer language, discover an unknown failure class, or diagnose a real production incident.

The exercise belongs in an ambient quality series because it exposes the contracts beneath the model. An evidence reference either matches the required format or does not; resolving the referenced material is a separate capability. A repeated finding either creates a duplicate or does not. A worker either possesses a publishing capability or does not. These questions should remain answerable when a model is later introduced. The demonstration is original educational code by Sandeep Belgavi, independent of Google's AQuA source.

Download both files and run them together

Save ambient_quality_demo.py and test_ambient_quality_demo.py into the same directory. Use Python 3.11 or later. The example uses the standard library and requires no API key, cloud account, or third-party package installation. Open a terminal in that directory. On macOS, use the Python 3 interpreter available in your environment:

python3 ambient_quality_demo.py
python3 -m unittest -v test_ambient_quality_demo.py

On Windows, use the Python launcher if it is installed:

py -3 ambient_quality_demo.py
py -3 -m unittest -v test_ambient_quality_demo.py

If your environment exposes the interpreter as python, substitute that executable and check its version first. Interpreter discovery is separate from program behavior. These platform command forms are guidance; this article does not claim a physical macOS execution or a cloud deployment.

The expected demonstration summary is:

deduplicated=1 findings=2 rejected=1 quarantined=1 published_actions=0

Compare the full output with the fixtures and tests. A matching summary is a useful first check, but it cannot establish that an unrelated dataset will be judged correctly.

The counters describe different decisions

The two findings come from explicit rules: a tool-result event reports an error, and an outcome event claims completion while its recorded state is pending. The successful tool event increments rejected because neither rule produces a finding. This does not mean a model-generated false positive was independently disproved, nor does it establish overall session quality. The name belongs to this small demonstration's output contract.

The comment containing injected instructions is quarantined because its kind is outside the accepted tool_result and outcome types. The code does not magically detect malicious language. An identical repeated event increments deduplicated; a reused event identifier with different contents is quarantined. This identity check applies only within one call to review, not across process restarts or independent batches.

The final counter is published_actions=0. The example has no publishing tool and performs no repair. In a future integration, preserve that separation through capabilities and credentials rather than relying on a counter. A findings store must not become a command queue that a privileged service executes without independent authorization.

A real locator is necessary but not sufficient

The current worker checks that evidence_ref matches a fixture: reference format. It does not fetch that reference, prove that the referenced object exists, match a source revision, or validate source lines. This is an explicit limitation. A production extension needs a resolver against an authorized evidence store and a policy for missing material. A plausible-looking identifier is not verified evidence.

Extend the exercise with an original shipment fixture: a tool reports failure while the outcome remains pending. That is different from a timeout followed by a confirmed warehouse receipt. The latter might require a communication correction rather than another shipment request. Add the receipt lookup as a separate capability with its own tests. Keep a healthy case beside each failure case so a broad rule cannot pass by flagging everything. Even a resolved source citation establishes traceability, not proof that a particular line caused the failure.

Keep inspected text from becoming instructions

The injected fixture is data supplied to the worker for inspection. It must not rewrite the worker's policy, suppress a rule, or authorize a new action. This small example demonstrates a bounded behavior under its own deterministic implementation. It does not establish that a future language-model integration will resist every prompt injection. Adding a model changes the attack surface and requires new tests.

A proposed extension passes sanitized evidence to a model only after deterministic validation. The model returns a constrained candidate finding, and code validates its fields and evidence references before storage. Neither the evidence text nor the model response receives production deployment credentials. Test malicious instructions in customer messages, tool results, retrieved documents, and source comments. The requirement is behavioral: the worker still observes its action boundary. A refusal sentence alone is not evidence that every tool boundary held.

Name the production work the example leaves open

A durable service needs authenticated ingestion, storage migrations, retention controls, concurrent-worker coordination, and a restart story. Add a unique finding key in persistent storage and test repeated delivery across process restarts. That protects the finding store from duplicate observations; it does not make a payment or shipment API idempotent. An external effect needs its own transaction contract. Make these separate test suites so one success cannot conceal the other's failure.

For a first live trial, feed an approved, redacted slice into a read-only worker and compare findings with independent labels. Set a maximum batch size, a runtime limit, and a pause mechanism. Define who reviews quarantined cases. Only after collection and judgment are understood should a model judge or scheduler be added. The next article supplies a measurement plan for that transition; the goal is to know precisely which new capability each stage demonstrates.

Source code and scope of the exercise

The downloadable example and companion tests are the primary references for this walkthrough. Inspect their fixtures and assertions before extending them. All records are synthetic. The output is an educational result, not a benchmark of Google AQuA, ADK, a model provider, or a production application.

The two original fixture files are offered under the linked MIT license. This applies to these teaching files; it does not replace the Apache-2.0 terms governing upstream Google code.