avowa-runtime 0.11.0__tar.gz

avowa_runtime-0.11.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Avowa, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

avowa_runtime-0.11.0/NOTICE

@@ -0,0 +1,4 @@
+Avowa Runtime SDK
+Copyright 2026 Avowa, Inc.
+
+This product includes software developed at Avowa, Inc. (https://avowa.ai).

avowa_runtime-0.11.0/PKG-INFO

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: avowa-runtime
+Version: 0.11.0
+Summary: Avowa Runtime SDK — emit live AI-inference signals to Avowa as evidence.
+Author: Avowa, Inc.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://avowa.ai
+Project-URL: Repository, https://github.com/Avowa-AI/avowa-runtime-sdk
+Project-URL: Issues, https://github.com/Avowa-AI/avowa-runtime-sdk/issues
+Keywords: avowa,ai-trust,evidence,observability,compliance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# Avowa Runtime SDK (Python)
+
+Emit **live AI-inference signals** to Avowa so your AI-trust claims are backed by
+runtime evidence — which model ran, in which region, whether customer data is used
+for training, and guardrail outcomes. This is the evidence posture tools (Vanta/Drata)
+can't capture: *how your AI actually behaves in production.*
+
+- **Stdlib-only** — no dependencies added to your app.
+- **Non-blocking** — a background worker sends signals; ~0ms added to inference.
+
+## Install
+
+**Fastest path — three lines, in the environment your app runs in** (Connections → Runtime SDK → *Generate setup token*):
+
+```bash
+pip install https://api.avowa.ai/public/sdk/avowa-runtime-sdk.zip      # public, code only (PyPI follows)
+avowa-run --init <setup-token> --api https://api.avowa.ai              # writes avowa.env (0600); nothing to paste
+avowa-run <your usual start command>                                   # auto-instrumented, no code change
+```
+
+`avowa-run --doctor` then confirms the key, the secret and your clock without sending anything.
+
+```bash
+pip install ./sdk/python          # local
+# (not on PyPI yet — install from the zip your Avowa console hands you)
+```
+
+## Configure
+Get the **ingest key** and **signing secret** from Avowa → **Connections → Avowa Runtime
+SDK** (both are minted when you enable that connector). Then set env vars (or pass them to
+the constructor):
+
+```bash
+export AVOWA_RUNTIME_KEY="..."                # identifies your connection (from your avowa.env)
+export AVOWA_RUNTIME_SECRET="avs_..."         # signs each signal (tamper-evident)
+export AVOWA_BASE_URL="https://api.your-avowa.com"   # required — no default; https only
+export AVOWA_REGION="us-east-1"
+```
+
+> **Tamper-evident and single-use (0.9+):** every request is HMAC-SHA256-signed over
+> `"<unix-timestamp>.<nonce>.<body>"` (headers `X-Avowa-Timestamp` / `X-Avowa-Nonce` /
+> `X-Avowa-Signature`). The server rejects bad signatures, requests outside a 5-minute window,
+> and any nonce it has already seen — so a signal can't be forged, altered or replayed.
+> **HTTPS only:** the SDK refuses a plain `http://` base URL unless it is localhost or a private
+> network (override with `AVOWA_ALLOW_HTTP=1`), and sends nothing when no URL is set.
+> **Off switch:** `AVOWA_DISABLE=1` — nothing is patched and nothing is sent, in every mode.
+> Keep the secret server-side — never ship it to a browser.
+
+## Usage
+
+```python
+from avowa_runtime import AvowaRuntime
+avowa = AvowaRuntime(region="us-east-1")   # reads AVOWA_RUNTIME_KEY / AVOWA_BASE_URL
+
+# A) Wrap one client explicitly. Everything it records is OBSERVED (model, endpoint, latency,
+#    errors) and it runs the local injection/PII scans for you. Pass scan=False to disable them.
+import anthropic, openai
+client = avowa.instrument_anthropic(anthropic.Anthropic(), region="us-east-1")
+client.messages.create(model="claude-opus-4-8", max_tokens=512, messages=[...])
+
+client = avowa.instrument_openai(openai.OpenAI(), region="us-east-1")
+client.chat.completions.create(model="gpt-4o", messages=[...])
+
+# ...but prefer zero-code auto-instrumentation (next section) — it covers clients you can't
+# reach by hand, which is where coverage is actually lost.
+
+# B) Wrap a block (times it + records the model/region):
+with avowa.track(model="claude-opus-4-8", region="us-east-1"):
+    resp = client.messages.create(...)
+
+# C) Record explicitly (e.g. after a guardrail check):
+avowa.capture(model="claude-opus-4-8", region="us-east-1",
+              train_on_data=False, guardrail_blocked=blocked, latency_ms=842)
+```
+
+Each signal feeds the **runtime_sdk** connector. Run a capture/sync (or the Change Feed)
+in Avowa and the signals become evidence. You only ever claim what you instrument — a field
+you don't pass is not sent, so it proves nothing.
+
+## Zero-code auto-instrumentation (recommended)
+
+`instrument_openai(client)` asks you to find *where the client is constructed*. In a real
+codebase that's the hard part — it may be a factory, five call sites, or inside LangChain /
+LlamaIndex / CrewAI where you can't edit it at all. Anything you miss shows up as **low traffic**
+rather than a missed integration, because Avowa publishes instrumentation coverage as a
+denominator. Auto-instrumentation patches the client **classes**, so every instance is covered
+no matter who builds it.
+
+**Credentials first, and there is nothing to type.** Your SDK download contains `avowa.env`
+already filled in — copy it into the directory you start your app from. The SDK reads **only
+`AVOWA_*` keys** out of it and a real environment variable **always wins**, so Kubernetes Secrets
+or Secrets Manager injection keeps working unchanged. (`AVOWA_ENV_FILE` points at a specific file;
+`AVOWA_NO_ENV_FILE=1` switches it off.) Setting them by hand on macOS/Linux is `export VAR=value` —
+plain `set VAR=value` is Windows CMD syntax and silently does nothing in bash/zsh.
+
+```bash
+# 1. Prefix how the process starts — nothing in your app changes. Best option for most teams.
+avowa-run uvicorn app:main --host 0.0.0.0
+avowa-run gunicorn -w 4 app:main
+# Docker:  CMD ["avowa-run", "uvicorn", "app:main"]
+
+# 2. Can't change the start command? Install a start-up hook once per environment.
+python -m avowa_runtime.auto --install     # then set AVOWA_AUTO=1  (--uninstall to remove)
+
+# 3. See what it patched.
+python -m avowa_runtime.auto
+```
+
+```python
+# 4. Or one import at your entry point (main.py, Django settings, Lambda handler):
+import avowa_runtime.auto
+```
+
+All four read config from the environment only: `AVOWA_RUNTIME_KEY`, `AVOWA_RUNTIME_SECRET`,
+`AVOWA_BASE_URL`, `AVOWA_REGION`, and `AVOWA_SCAN=0` to disable the local scan. Import order
+doesn't matter — an import hook patches provider SDKs whenever they load. Gunicorn/uvicorn
+workers inherit the environment, so workers are instrumented and Avowa sums their signals.
+
+The `.pth` hook does nothing at all unless `AVOWA_AUTO=1`, so installing the SDK can never
+silently start instrumenting something.
+
+### Nothing showing up?
+
+```bash
+python -m avowa_runtime.auto --check       # credentials + reachability. Sends NO signal:
+                                           # a synthetic event would show on your trust
+                                           # profile as inference that never happened.
+AVOWA_DEBUG=1 avowa-run <your command>     # trace patch → capture → send, metadata only
+```
+
+```
+[avowa:debug] patched openai.OpenAI
+[avowa:debug] captured gpt-4o-2026-05-13 via api.openai.com (32ms)
+[avowa:debug] sent gpt-4o-2026-05-13 via api.openai.com (32ms) → HTTP 200
+```
+
+In order of likelihood: **no inference has run yet** (starting the app proves nothing — send a
+request that calls the model); **the app doesn't use the `anthropic`/`openai` Python SDKs** (raw
+`requests`/`httpx`, or a provider with no wrapper — use `capture()`); or **delivery is failing**.
+The first failed send prints one line naming the cause — a wrong key, a wrong base URL, a blocked
+host — and then stays quiet. Silence on that line means signals are being delivered.
+
+`AVOWA_DEBUG` output is metadata-only, like the wire format. It never prints prompts or responses;
+there's a test asserting that, because debug output is what people paste into tickets.
+
+### What the SDK reads off each call
+
+Controls that would otherwise be self-reported are visible in the call itself. The SDK reads the
+facts and sends them as they are; Avowa evaluates them on its side and grades the result as
+**observed (L3)** rather than asserted (L2). The SDK draws no conclusions of its own.
+
+| Fact sent | Read from | Evidence it feeds |
+|---|---|---|
+| `requested_model` + `model` | the model id on the request, and the one in the response | AI supply-chain integrity |
+| `stop_reason` | the provider's own stop / finish code | Guardrails / content filtering |
+| `structured_output` | the call used `parse()` or supplied a schema | Output handling |
+| `token_ceiling`, `error` | the request's output-token limit; the exception type on a failed call | Rate & cost limits |
+| token usage (`input_tokens`, `output_tokens`, cache reads and writes) | the provider's own usage report on the response | Rate & cost limits · volume |
+| `system_prompt_present`, `tool_choice`, `response_format_type`, `streaming` | the request's settings — whether a system prompt was set, never what it says | System-prompt protection · agency · output handling |
+| `messages_user` / `_assistant` / `_tool`, `input_images` / `_files` / `_audio`, `prompt_chars`, `output_chars` | counts and sizes only | Autonomy · data types processed |
+| `client_max_retries`, `client_timeout_s` | how your client is configured | AI-path resilience |
+| `pii_families`, `injection_families` | which named pattern families the local scan matched (never the text) | Sensitive-data leakage · prompt injection |
+| `temperature`, `top_p`, `seed`, `choices_n`, `stop_sequences` (a count), `reasoning_effort`, `thinking_enabled` | the request's sampling and reasoning settings | Reproducibility · output handling |
+| `store_requested`, `service_tier_requested` / `service_tier` | whether the app asked the provider to store the output; the tier requested and served | Data retention · no-training |
+| `end_user_id_present`, `metadata_present` | **whether** an end-user id or metadata travelled with the call — never the id | Accountability · per-user attribution |
+| `provider_filtered`, `provider_filter_categories`, `provider_block_reason`, `guardrail_configured`, `safety_settings` (a count) | the provider's **own** safety verdict (Azure content filters, Gemini block reasons, a Bedrock guardrail) — category names only | Guardrails / content filtering |
+| `system_fingerprint` | the provider's backend configuration id | AI supply-chain integrity · model change |
+| `http_status`, `provider_error_code`, `retry_after_s` | a failed call's status and the provider's error **code** — never the error message, which can echo the request | Rate & cost limits · AI-path resilience |
+| `ttft_ms` | time to the first streamed chunk | Availability · performance |
+| `provider_lib` / `provider_lib_version`, `python_version`, `app_frameworks` | which provider library, Python and agent frameworks the app runs | AI bill of materials |
+| `app_region` + `app_region_source` | the region code from your platform's own variable (`AWS_REGION`, `FLY_REGION` …) | Where processing happens — cross-border transfers |
+
+### New metadata without a redeploy
+
+Providers add metadata fields over time (a new safety verdict, a new service tier). Rather than ask
+you to upgrade for each one, Avowa can ask the SDK to read a further **metadata** field by name. The
+list arrives on the response to a signal the SDK already sends, authenticated with your connection's
+secret, and only when your copy is out of date.
+
+- **Data, never code.** An entry is a name, a provider and an attribute path. The SDK reads that path
+  and nothing else; no code is downloaded or run.
+- **The guard is in the SDK, not in the list.** A path through any content-bearing name (`content`,
+  `text`, `messages`, `input`, `output`, `arguments`, `system` …) or a private attribute is refused,
+  and only a number, true/false or a short code (letters, digits, `_.:-`, at most 40 characters) can
+  come back. No list Avowa sends can widen what leaves your process.
+- **See it, or switch it off.** `python -m avowa_runtime.auto` prints the active list.
+  `AVOWA_REMOTE_FIELDS=off` turns it off; only the built-in metadata above is then read.
+
+**If your app gives the model tools, the agentic evidence comes free too.** Nobody else can produce
+this, because it isn't in a log or a config file — it only exists in the call:
+
+| Flag | How it is derived | Claim it proves |
+|---|---|---|
+| `tools_offered` | the tool definitions supplied on this call — the grant, as it really was | Agent tool inventory |
+| `tools_invoked` | the tool-use blocks the model actually returned (parallel calls included) | Agent tool inventory · tool-permission scoping |
+| `autonomy_depth` | prior assistant turns that requested tools — steps taken before returning to a human | Autonomy bounds |
+
+**Tool names only.** Schemas, descriptions and arguments are read for the name and dropped
+in-process: they carry business logic and sometimes examples containing real data, so they are
+treated exactly like prompt text.
+
+Unused grants are the point. A tool handed to the model on every call and never invoked is standing
+authority nobody is watching — OWASP LLM06 — and Avowa reports it as a finding. Scoping is only
+*proven* when every granted tool is exercised; an unused one is never called proof of over-scoping
+either, because a short window can't tell a rarely-used tool from an unnecessary one.
+
+Nothing here defaults to `True`, and a flag is **omitted entirely** when the call does not answer
+the question — a field the SDK cannot see is never filled in on your behalf. `autonomy_depth` is
+reported as unknown rather than `0` when the message history isn't a shape it recognises, because
+`0` would read as "fully attended".
+
+Everything else (`human_reviewed`, `decision_logged`, `ai_disclosed`, `grounded`,
+`rationale_present`, `fairness_checked`, `uncertainty_flagged`, `rate_limited`,
+`system_prompt_protected`, `eval_score`) is genuinely invisible from the call, so it stays an
+explicit `capture(...)` argument and is graded self-reported. **Pass only what your app actually
+enforces** — asserting a control you don't have is the thing Avowa exists to catch.
+
+Where a signal is built from ONE field, calls the SDK observed are graded on their own and the
+app-reported ones are named and excluded — an assertion can neither inflate an observation nor
+suppress it. Where a signal blends several fields (guardrails combines your guardrail names and PII
+counts with the block outcome) it stays as strong as its weakest field, so every call must be
+observed for it to be graded observed.
+
+`action_class` (read / write / external / financial) is **not** derived. The SDK sees a tool's name,
+not its consequence, and guessing would put a judgement in your mouth — pass it explicitly if you
+want human-approval coverage measured over consequential actions only.
+
+### Which providers auto-instrument
+
+| Provider | Classes patched | Notes |
+|---|---|---|
+| Anthropic | `Anthropic`, `AsyncAnthropic` | covers `messages.create` and `messages.parse` |
+| Claude on Bedrock / Vertex | `AnthropicBedrock`, `AnthropicVertex` | covered when you use the `anthropic` SDK's own clients |
+| OpenAI | `OpenAI`, `AsyncOpenAI` | covers `chat.completions.create` / `.parse` (incl. the `beta` namespace) and `responses.create` / `.parse` |
+| Azure OpenAI | `AzureOpenAI`, `AsyncAzureOpenAI` | the Azure host is recorded, which is what evidences the inference region instead of assuming it |
+| Any OpenAI-compatible endpoint (Together, Groq, Fireworks, vLLM, OpenRouter, local) | via the `openai` classes | the real host is recorded, not `api.openai.com` |
+| Amazon Bedrock (boto3 `bedrock-runtime`) | `from avowa_runtime.adapters import instrument_bedrock` → `instrument_bedrock(avowa, client)` | `converse` and `invoke_model`; the Bedrock endpoint host and region, `stopReason` (a `guardrail_intervened` stop is the guardrail firing, observed), tool grants from `toolConfig` |
+| Google Gemini (`google-genai`) | `instrument_gemini(avowa, client)` | `models.generate_content` (sync and `aio`); served `model_version`, `finish_reason` (SAFETY / PROHIBITED_CONTENT = blocked), Vertex vs AI Studio host |
+| LangChain / LangGraph | `from avowa_runtime.langchain import AvowaCallbackHandler` → `callbacks=[AvowaCallbackHandler()]` | one signal per model call from the framework's own events, tool names from `on_tool_start`. Do not combine with a wrapped client — the call would count twice |
+| `mistralai`, `cohere` | — | no wrapper yet: `avowa.track(...)` / `avowa.capture(...)`, graded as self-reported |
+
+**Async clients are fully supported** — the signal is recorded after the `await`, not when the
+coroutine is created, so `latency_ms` is the real call duration and a failure is recorded as a
+failure.
+
+**Streaming is captured when the stream ends.** With `stream=True` the wrapper returns a proxy
+over the provider's iterator (sync or async, context manager included) that watches the chunks go
+by — the served model, the stop/finish reason, the output text for the local scan — and records
+once, with latency measured to the last chunk, when the stream is exhausted or closed. Nothing is
+recorded before that, because nothing is known before that. Anthropic's `messages.stream()` helper
+is not wrapped yet; call `capture(...)` after it closes.
+
+**Check the install without sending anything:** `python -m avowa_runtime.auto --doctor` asks the
+server who this key is — connection, environment, whether the plan allows capture, whether your
+secret signs correctly, your clock skew, and when it last heard from you.
+
+Nothing about your provider changes how evidence is graded. What matters is observed vs
+asserted, below — a manual `capture()` with observed fields outranks a wrapped call carrying
+only self-reported booleans.
+
+## Observed vs asserted — how Avowa grades what you send
+
+Not every field is worth the same, and Avowa will not pretend otherwise.
+
+| | What it is | Grade |
+|---|---|---|
+| **Observed** | The SDK worked it out itself — the model the API returned, the host it dialled, latency, errors, and the counts its own local detectors produced. | **L3 · live-verified** |
+| **Asserted** | A boolean your application passed about itself (`output_validated=True`). The HMAC proves the transport wasn't tampered with; it proves nothing about whether the claim is true. | **L2 · runtime-asserted** |
+
+An assertion is still worth more than a questionnaire answer — it's continuous, timestamped and
+signed — but it is a self-report, and a buyer is told so. **Prefer the observed fields.** They cost
+you nothing extra and they're the only ones that read as independently verified.
+
+Avowa also reports **instrumentation coverage**: if a flag rides on 5 of your 1,000 calls, the
+evidence says `5/1000 (0.5% of traffic)`, not `5/5`.
+
+**Core**
+
+| Field | Proves | Graded |
+|---|---|---|
+| `model` | `ai_components.models` | observed |
+| `endpoint` | `subprocessors` (observed egress) + `data.data_residency_jurisdiction` where the host encodes a region | observed |
+| `scan_prompt` → `injection_suspected` | `ai_security.prompt_injection` | observed |
+| `scan_output` → `pii_detected` | `ai_security.sensitive_disclosure` | observed |
+| `error` / `retries` / `fallback_model` | `resilience.ai_path` | observed |
+| `region` | `data.data_residency_jurisdiction` | observed if derivable from `endpoint`, else asserted |
+| `train_on_data=false` | `training_posture.trains_model_weights_on_customer_data` | asserted |
+| `guardrail_blocked` / `guardrail` / `blocked_category` | `responsible_ai.model_monitoring` + `guardrails` (+ live red-teaming) | asserted |
+
+### Local detection, metadata egress
+
+`scan_prompt` and `scan_output` are matched **inside your process** and dropped. Avowa receives an
+integer count and nothing else — never the text. That is what lets a leak or an attack be evidenced
+without Avowa ever processing your prompts.
+
+A detection is evidence an attack *arrived*, not that it was *stopped*: injection patterns your app
+doesn't report blocking, or PII still present in egress after your redaction ran, are reported as
+**unresolved exposure** rather than a passing control.
+
+**Responsible AI** (pass the flags your app enforces)
+
+| Field | Proves |
+|---|---|
+| `decision_logged` | `responsible_ai.decision_audit` + `prompt_output_logging` |
+| `human_reviewed` | `ai_components.human_oversight` |
+| `rationale_present` | `responsible_ai.decision_logic` (explainability) |
+| `ai_disclosed` | `responsible_ai.ai_disclosure` |
+| `uncertainty_flagged` | `responsible_ai.uncertainty_handling` |
+| `fairness_checked` | `responsible_ai.bias_detection` |
+
+**AI security — OWASP LLM Top 10 + agentic** (the moat: proven live from the call path, which no posture tool or static pentest can show)
+
+| Field | Proves | OWASP |
+|---|---|---|
+| `injection_blocked` | `ai_security.prompt_injection` | LLM01 |
+| `pii_redacted` | `ai_security.sensitive_disclosure` | LLM02 |
+| `model_pinned` | `ai_security.model_supply_chain` | LLM03 |
+| `output_validated` | `ai_security.output_handling` | LLM05 |
+| `tool_authorized` | `ai_security.excessive_agency` (agent tool-scoping) | LLM06 |
+| `action_authorized` | `ai_security.action_authorization` (high-impact action gating) | agentic |
+| `system_prompt_protected` | `ai_security.system_prompt_protection` | LLM07 |
+| `grounded` | `ai_security.groundedness` (hallucination resistance) | LLM09 |
+| `rate_limited` | `ai_security.rate_limiting` (abuse / DoS) | LLM10 |
+| `eval_score` (number) | `ai_governance.model_evaluation` | — |
+
+```python
+# prove AI-security controls live — pass what your inference path enforces on each call:
+avowa.capture(model="claude-opus-4-8", region="us-east-1", train_on_data=False,
+              injection_blocked=False, pii_redacted=True, output_validated=True,
+              system_prompt_protected=True, grounded=True, tool_authorized=True,
+              action_authorized=True, model_pinned=True, rate_limited=False, eval_score=0.94)
+```
+
+## Notes
+- Sends are best-effort and never raise into your request path.
+- `avowa.flush()` is registered at process exit; call it manually before a short-lived job ends.
+- Only metadata is sent — never prompts, outputs, or customer data.