Metadata-Version: 2.5
Name: ai-hats-observe
Version: 0.10.0
Summary: Session logging engine for the ai-hats framework — session lifecycle, versioned trace/audit schema, and a surface-agnostic transcript-parser adapter.
Project-URL: Homepage, https://github.com/muratovv/ai-hats
Project-URL: Repository, https://github.com/muratovv/ai-hats
Project-URL: Changelog, https://github.com/muratovv/ai-hats/blob/master/packages/ai-hats-observe/CHANGELOG.md
Author-email: muratovv <f@muratovv.me>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-hats,audit,observability,session,trace,transcript
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: ai-hats-core>=0.13.0
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# 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](https://github.com/muratovv/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`](https://pypi.org/project/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 enriched `AuditWriter` that turns a transcript into
  `audit.md` + a versioned `metrics.json`.
- **Versioned trace/audit schema** — a `schema_version` on the metrics surface,
  with a wired (initially empty) migration seam.
- **Surface-agnostic parsing** — a `TranscriptParser` adapter: the `AuditWriter`
  holds no provider-specific parsing; the concrete `ClaudeParser` (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`).
