ai-hats-observe
A standalone session-logging engine: open a session on a bare directory,
append trace entries, write an incremental audit, and finalize a versioned
metrics.json — with no configuration, no worktree engine, and no
ai-hats.yaml.
ai-hats-observe is the observability core extracted from the
ai-hats framework (ADR-0014 Phase 1, T15).
It has no dependency on the ai-hats integrator: everything below runs against a
plain directory. Its only runtime dependency is
ai-hats-core (dependency-free
filesystem primitives + the migration seam).
What it owns
- Session lifecycle —
SessionManager/Session: allocate a session directory, resolve its artifact paths, list/filter past sessions. - Trace + audit writer —
log_trace,init_audit,append_audit,finalize_audit; the enrichedAuditWriterthat turns a transcript intoaudit.md+ a versionedmetrics.json. - Versioned trace/audit schema — a
schema_versionon the metrics surface, with a wired (initially empty) migration seam. - Surface-agnostic parsing — a
TranscriptParseradapter: theAuditWriterholds no provider-specific parsing; the concreteClaudeParser(structured JSONL + trace-chrome fallback) is one implementation. A new surface (Gemini, or a future CLI) plugs in its own parser — the writer never changes.
Session privacy
New session directories are created with mode 0700. Sensitive artifacts are
created and rewritten with mode 0600, including prompts, role materialization,
traces, audits, metrics, transcripts, reasoning, usage, and raw PTY captures.
These permissions are enforced independently of the caller's umask and apply to
every provider that uses the observe session API. Existing session trees are not
migrated or rewritten.
Extending to a new surface
The parser is carried by the session's provider, not a central registry: a
Provider yields its TranscriptParser, and the integrator injects it into the
AuditWriter. Adding a surface means shipping a parser that satisfies the
TranscriptParser protocol and a provider that names it — no edit to
ai-hats-observe internals.
Dependency direction
ai-hats-observe imports only ai-hats-core and the standard library. It
never imports the ai-hats integrator; ai-hats imports from here. The boundary
is enforced by an AST import-lint (test_observe_boundary.py).
Metadata
Release files for ai-hats-observe 0.19.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_hats_observe-0.19.0.tar.gz | 136.7 kB | With provenance | Details for ai_hats_observe-0.19.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_hats_observe-0.19.0-py3-none-any.whl | Python 3 | none | any | Details for ai_hats_observe-0.19.0-py3-none-any.whl |
Total release size: 223.6 kB
Release files / ai_hats_observe-0.19.0.tar.gz
| Download URL | ai_hats_observe-0.19.0.tar.gz |
|---|---|
| Size | 136.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf9f76ae8181a43b087e831033f9eaba1f71fcecd0a6b9c5f7e473c7a5a47966
|
|
BLAKE2b-256 checksum How to use checksums |
c975ff9b456c0d3e0b2c6c458d2687baeaca49c6dd3a790f5e9b0bb1d328ed5e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / ai_hats_observe-0.19.0-py3-none-any.whl
| Download URL | ai_hats_observe-0.19.0-py3-none-any.whl |
|---|---|
| Size | 86.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ac4b243196d0e2249ce0d69258d140d7d4b7f37c03dd983ce40307edf62f8f3
|
|
BLAKE2b-256 checksum How to use checksums |
3ec9a5d1133e27caecdb35afe11778cc066e9692ab59a3c38c5469741116bc79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logSecurity for ai-hats-observe 0.19.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ai_hats_observe-0.19.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.