epytome 0.1.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 with rich Typer output:

Usage: epytome [OPTIONS] COMMAND [ARGS]...


 Epytome — structured Knowledge Bases for agentic applications.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ find           Search the knowledge base for items matching QUERY.           │
│ read           Read the full content of an Asset by its ID.                  │
│ resolve        Resolve a named Entity from the knowledge base.               │
│ assertions     Query structured assertions from the knowledge base.          │
│ ingest         Ingest a file as an Asset into the knowledge base snapshot.   │
│ list-entities  List entities in the KnowledgeBase with optional filtering,   │
│                pagination, and sorting.                                      │
│ list-assets    List assets in the KnowledgeBase with optional filtering,     │
│                pagination, and sorting.                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

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

(coming soon) Epytome's documentation is being consolidated into a new MkDocs site.

Contributing

Epytome is still in an MVP-shaping stage, so contributor feedback is especially valuable.

For now, useful places to start are:

• inspect the tests under tests/
• use uv sync to set up a local environment
• run the test suite with uv run pytest
• open an issue or pull request if you want to propose an improvement

A dedicated CONTRIBUTING.md and a fuller public docs site are planned as separate follow-on documentation work.