epytome 0.2.0

Structured, provenance-aware knowledge layer for Python applications and AI-agent workflows

Epytome is a structured, provenance-aware knowledge layer for Python applications and AI-agent workflows.

It helps developers model assets, entities, assertions, and predicates in a compact API that is easier to inspect, trust, and evolve than ad hoc context pipelines.

Why Epytome

• Structured knowledge instead of prompt stuffing: represent what your system knows as typed Python objects.
• Visible provenance: track where assets and assertions came from and inspect that provenance directly.
• Practical retrieval: search, resolve, read, and query knowledge through one KnowledgeBase API.
• Predicate support with honest scope: define semantic relationships and governance without pretending this is already a full reasoning engine.

Who it is for

Epytome is currently aimed at:

• Python backend engineers building knowledge-aware services
• ML and agent engineers grounding LLM or agent workflows
• teams building agentic applications that need more reliable context handling
• contributors interested in provenance-aware application infrastructure

If you already work with tools like FastAPI, Pydantic, SQLAlchemy, Typer, or coding-agent workflows, Epytome should feel familiar: explicit models, simple composition, and a Python-first API.

What you can do today

Today, Epytome gives you a compact, focused surface for:

• creating a KnowledgeBase backed by an InMemoryStore
• ingesting Asset, Entity, Assertion, and Predicate records
• materializing assets from inline text or files
• searching across assets, entities, and assertions
• resolving entities by ID, canonical name, or alias
• querying assertions by subject, predicate, and temporal/provenance filters
• inspecting provenance with provenance_of(...)
• generating compact entity context blocks with describe(...)
• working through a CLI for search, read, resolve, assertions, ingest, and listing commands

Install

It currently requires Python 3.13+.

Install it with pip:

pip install epytome

Then use it directly:

python
epytome --help

If you use uv to manage project dependencies:

uv add epytome

Then run it through uv:

uv run python
uv run epytome --help

If you are working from a cloned checkout and want an editable install:

pip install -e .

Quickstart

Start with an in-memory knowledge base, ingest a few domain objects, and query them back:

from epytome import Asset, Assertion, Entity, InMemoryStore, KnowledgeBase

kb = KnowledgeBase(store=InMemoryStore())

guide = Asset.from_text(
    "Billing Deploy Guide",
    "Deploy the billing API after the database migration completes.",
    provenance={"actor": "alice", "source_type": "doc"},
)

billing_api = Entity(
    entity_type="service",
    canonical_name="billing-api",
    aliases=["billing"],
    provenance={"actor": "alice"},
)

platform_team = Entity(
    entity_type="team",
    canonical_name="platform-team",
    provenance={"actor": "alice"},
)

ownership = Assertion(
    subject=billing_api.entity_id,
    predicate="owned_by",
    object=platform_team.entity_id,
    source_asset_ids=[guide.asset_id],
    provenance={"actor": "sync-job", "run_id": "run-42"},
)

for item in (guide, billing_api, platform_team, ownership):
    kb.ingest(item)

results = kb.find("billing")
entity = kb.resolve("billing")

print(results[0].item_type)
print(entity.canonical_name)

This is the core Epytome loop:

1. create a KnowledgeBase
2. ingest assets, entities, and assertions
3. search with find(...)
4. inspect the retrieved objects with resolve(...), read(...), and provenance_of(...)

If you want to inspect the search results explicitly, iterate them rather than assuming a particular top hit:

for result in results:
    print(result.item_type, result.score)

Provenance

Provenance stays attached to the things your system knows, so you can inspect where knowledge came from:

asset_provenance = kb.provenance_of(guide.ref)
assertion_provenance = kb.provenance_of(ownership.ref)

print(asset_provenance.actor)
print(assertion_provenance.run_id)

This makes it easier to trace retrieved context back to documents, operators, jobs, and ingestion flows.

Predicates

Predicates give you a governed vocabulary for relationships instead of leaving them as ad hoc strings:

from epytome import Governance, Predicate, PredicateStability, PredicateTier

depends_on = Predicate(
    predicate_id="depends_on",
    label="depends on",
    tier=PredicateTier.CORE,
    aliases=["requires"],
    subject_types=["service"],
    object_types=["service"],
    governance=Governance(
        stability=PredicateStability.STABLE,
        owner="platform-team",
    ),
)

kb.ingest(depends_on)

resolved = kb.resolve_predicate("requires")
kb.validate_predicate_usage("depends_on", "service", "service")

print(resolved.predicate_id)

That gives teams a reusable relationship model with aliases, hierarchy hooks, governance metadata, and validation support.

CLI

The CLI exposes the same ideas from the terminal. For local and coding-agent workflows, initialize a project-local JSON snapshot once and then reuse it across short-lived commands:

epytome init
epytome ingest docs/architecture.md
epytome find "billing" --json
epytome status

epytome init creates .epytome/kb.json. Later commands discover the nearest .epytome/kb.json from the current directory or a parent directory, load it into InMemoryStore, and save it back after write-side commands such as ingest.

You can override discovery with --kb <path> or EPYTOME_KB. Explicit --kb wins over EPYTOME_KB, and both win over the discovered project snapshot.

Current objectives

Epytome is currently focused on helping teams:

• model knowledge as typed Python objects instead of ad hoc context blobs
• preserve provenance so retrieved context can be inspected and trusted
• search, resolve, read, and query knowledge through a compact API and CLI
• define semantic relationships with a governed predicate vocabulary

The emphasis is on a clear, dependable core that fits naturally into real Python workflows.

Documentation

Epytome's public documentation is now organized as a MkDocs site under docs/.

To browse it locally:

uv run --group docs mkdocs serve

To build it statically:

uv run --group docs mkdocs build

Contributing

Contributor feedback is especially valuable.

For now, useful places to start are:

• inspect the tests under tests/
• use uv sync --group dev --group docs to set up a local environment
• run the test suite with uv run pytest
• read CONTRIBUTING.md for the contributor workflow and expectations
• open an issue or pull request if you want to propose an improvement