aether-observer 0.1.3

Graphiti/Kuzu knowledge-graph builder with graph-data and agent drift detection.

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

python -m pip install aether-observer

For live Graphiti/Kuzu ingestion:

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:

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

Input Format

Each JSONL record is an episode:

{"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

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.