Metadata-Version: 2.4
Name: ai-hats-observe
Version: 0.2.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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: ai-hats-core>=0.5.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.

## 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`).
