sift-kg boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

sift-kg is in scope as a memory/knowledge/context-engineering system. Its intended use is to turn documents into a retained knowledge graph, maintain that graph through build and resolution commands, and expose it to humans and external AI agents. The boundary covers the whole shipped repository product, not merely its library API or its extraction computation. The bundled agent skill is part of this boundary: it prescribes how an external agent reloads and consumes retained content across sessions. It is evidence of intended host use, not evidence that a host actually follows it (SRC-1, README.md, .agents/skills/sift-kg/SKILL.md).

Use sift-kg as an AI second brain — a persistent knowledge graph your agent operates from across sessions. --- .agents/skills/sift-kg/SKILL.md

The shipped entry points are the sift console application, module invocation and Python exports. The CLI itself performs extraction, build, resolution, review, application of decisions, narrative generation and retrieval; it is not an excluded application around a narrower library. pipeline.py separately offers explicit-parameter library functions and an extract/build/narrate driver. Both callers belong to the target (SRC-1, pyproject.toml, src/sift_kg/__main__.py, src/sift_kg/__init__.py, src/sift_kg/cli.py, src/sift_kg/pipeline.py).

sift = "sift_kg.cli:app" --- pyproject.toml

The functional loop includes document reading and chunking; model-backed schema discovery and extraction; per-document extraction persistence and reuse; deterministic graph construction and deduplication; model-proposed entity resolution; review decisions; graph mutation; community and narrative artifacts; and later reload for query, topology, search, export and visualization. The extraction caller writes cached extraction JSON; build consumes extraction files and saves graph_data.json; resolution and review use YAML decision files; apply-merges reloads and updates the graph. The CLI's topology and query commands reload that retained graph to return agent-facing structure (SRC-1, src/sift_kg/extract/extractor.py, src/sift_kg/pipeline.py, src/sift_kg/cli.py).

extraction_path = extraction_dir / f"{doc_id}.json" extraction_path.write_text(extraction.model_dump_json(indent=2)) --- src/sift_kg/extract/extractor.py

kg = KnowledgeGraph.load(graph_path)

--- Input resolution ---

matched_id: str | None = None --- src/sift_kg/cli.py

Admission and maintenance include automatic processing as well as human decisions. In particular, the shipped reviewer can automatically confirm sufficiently confident proposals; the boundary does not assume every merge requires a separate human approval. The simple library pipeline does not perform the review loop itself, but that loop remains included through the shipped CLI and library stage functions (SRC-1, src/sift_kg/resolve/reviewer.py, src/sift_kg/cli.py, src/sift_kg/pipeline.py).

Proposals where ALL members have confidence >= auto_approve_threshold are automatically confirmed without interactive review. --- src/sift_kg/resolve/reviewer.py

Repository coverage

The tracked top-level tree was enumerated at the frozen commit. “Included” defines analytical scope; it does not assert exhaustive file-level inspection. Initial inspection below distinguishes full reads, bounded code reads and symbol/call-site scans. No material shipped loop path is deliberately excluded or unavailable.

Frozen boundary and external limits

The sole frozen source is SRC-1 at d786991c024f5401f113fc0cb70aee96dd1bd3bf; checkout HEAD was checked against the acquired revision. The analysis cutoff is 2026-10-18, the supplied run date, not an assertion about a deployment date. Evidence is code-grounded with source-native doctrine/design. Later changes, linked external repositories and moving web pages are outside the evidence set.

External dependencies include model providers reached through LiteLLM, document/OCR engines, NetworkX, optional embedding/clustering packages, and browser/rendering libraries (SRC-1, pyproject.toml, src/sift_kg/extract/llm_client.py, src/sift_kg/ingest/reader.py, src/sift_kg/visualize.py). Their internals and service operation are not frozen here; the analysis can explain sift-kg's integration code but cannot establish provider reliability, OCR accuracy or embedding quality. User corpora and custom schemas outside this commit are also absent, preventing general accuracy and workload-cost conclusions.

The external agent runtime and its response generation remain outside the target; the shipped skill and retrieval interfaces are inside. Therefore this run can establish the prescribed memory-consumption route, not actual cross-session agent compliance or improved answers. Civic Table is a separately described downstream platform, not a shipped local caller; its analyst/legal verification responsibilities are not attributed to sift-kg (SRC-1, README.md). No target code, tests, examples, models or services were executed. There is no inspected execution trace or causal experiment, so operational success and causal benefit remain unestablished. Available but uninspected source files are inspection limits, not access gaps, and remain available at the same registered commit.

Source register