Metadata-Version: 2.4
Name: aether-observer
Version: 0.1.3
Summary: Graphiti/Kuzu knowledge-graph builder with graph-data and agent drift detection.
Author: Aether
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: graphiti
Requires-Dist: graphiti-core[kuzu]<0.30.0,>=0.29.0; extra == 'graphiti'
Description-Content-Type: text/markdown

# Aether Observer

Local Python CLI for building a temporal knowledge graph with Graphiti/Kuzu and scoring drift while
the graph is built.

The package has two layers:

- deterministic drift scoring over JSONL episodes
- optional live ingestion into `getzep/graphiti` using the Kuzu backend

## Install

```bash
python -m pip install aether-observer
```

For live Graphiti/Kuzu ingestion:

```bash
python -m pip install "aether-observer[graphiti]"
```

Graphiti may require LLM and embedding provider environment variables, depending on your provider
configuration.

For local development from this repository:

```bash
python -m pip install -e ".[graphiti,dev]"
```

## Input Format

Each JSONL record is an episode:

```json
{"id":"e1","timestamp":"2026-05-15T00:00:00Z","content":"Alice joined Acme.","content_type":"text","source":"seed","agent_id":"agent-a","task_id":"build-kg","entity_types":["Person","Org"],"relation_types":["JOINS"],"tool_calls":["extract"],"expected_intent":"add employment fact","outcome":"success"}
```

Important optional fields:

- `entity_types`, `relation_types`, `graph_nodes`, `graph_edges`, `embedding`, `contradictions`, `invalidations`
- `tool_calls`, `handoff`, `coordination_failure`, `boundary_violation`, `human_intervention`
- `expected_intent`, `observed_intent`, `reasoning_trace`, `outcome`

## CLI

```bash
kg-drift init --db .kg-drift/graphiti.kuzu
kg-drift ingest --input fixtures/sample_episodes.jsonl --db .kg-drift/graphiti.kuzu
kg-drift score --input fixtures/sample_episodes.jsonl --window-size 4 --out report.json
kg-drift export --input fixtures/sample_episodes.jsonl --format json
```

`score` emits rolling-window metric scores and a composite Agent Stability Index style score. Drift
is flagged when the composite `asi_score` remains below the threshold for the configured number of
consecutive windows.
