agos-context

A small, deterministic kernel for bounded context graphs. It performs no I/O and grants no authority.

authorized owner records -> Contributions -> SliceOrder -> bounded Slice
                                                        -> exact traversal

The package owns four semantics:

Authorization, acquisition, storage, search, embeddings, models, prompts, ontologies, entity resolution, canonical records, and writes belong to the integrating application.

Install

python -m pip install agos-context
# or
uv add agos-context

Example

from datetime import datetime, timezone

from agos_context.compile import compile_slice, retention_order
from agos_context.graph import Contribution, Limits, Node, Pin, Policy, Ref, link, stable_hash
from agos_context.traversal import SourceClosure, neighborhood

memory = Pin(ref=Ref(owner="memory", kind="memory", id="m1"), revision="1")
document = Pin(ref=Ref(owner="documents", kind="document", id="d1"), revision="4")
memory_node = Node(pin=memory, record_class="record", label="Debt maturity")
document_node = Node(pin=document, record_class="evidence", label="Credit agreement")
supported_by = link(
    owner=memory,
    source=memory.ref,
    predicate="memory.supported_by",
    target=document.ref,
    family="source",
)

parts = (
    Contribution(
        owner="memory",
        nodes=(memory_node, document_node),
        links=(supported_by,),
        policies=(Policy(owner="memory", name="read", revision=stable_hash(["memory-read-v1"])),),
    ),
    Contribution(
        owner="documents",
        nodes=(document_node,),
        policies=(Policy(owner="documents", name="read", revision=stable_hash(["document-read-v1"])),),
    ),
)
nodes = tuple(node for part in parts for node in part.nodes)
links = tuple(row for part in parts for row in part.links)
now = datetime(2026, 1, 1, tzinfo=timezone.utc)

context = compile_slice(
    purpose="research",
    roots=(memory.ref,),
    effective_as_of=now,
    observed_before=now,
    nodes=nodes,
    order=retention_order(roots=(memory,), nodes=nodes, links=links),
    links=links,
    policies=tuple(policy for part in parts for policy in part.policies),
    limits=Limits(max_nodes=8, max_links=8),
)
selected = neighborhood(
    context,
    root=memory,
    depth=1,
    source_closure=SourceClosure(),
    limits=Limits(max_nodes=8, max_links=8),
)

assert {node.pin for node in selected.nodes} == {memory, document}
assert selected.links == (supported_by,)

Applications construct closed contributions from already-authorized records. The purpose compiler explicitly chooses which contributions to flatten and how to order them; the generic kernel does not infer policy. The caller supplies purpose, time, order, policy, limits, and finite values explicitly. A Slice is immutable and content-addressed. Traversal can only select records already present in that Slice; selected semantic records can require exact source links or report their absence.

Links are navigation, not inferred truth. Labels are presentation, not authority. Consumers reopen the exact canonical owner revision before relying on a selected record.

Relationship to domain kernels

Context composes references to domain results; it does not own their meaning. An integrating application may project a canonical domain graph—for example, Property evidence—into a Contribution:

canonical domain result -> optional Host projection -> Contribution
                                                        |
                                      + contributions -> bounded Slice

That projection is optional, lossy, and owned by the application. A Node or Link makes a result navigable; it does not establish a domain fact, grant authority, or provide a write path back to the owner. Consumers reopen the exact canonical domain revision for truth or correction.

Context therefore does not depend on Property, Memory, or another domain kernel, and domain kernels do not depend on Context. A shared adapter belongs in neither kernel until a concrete integration proves a stable contract.

Develop

uv sync --locked --all-groups
uv run pytest
uv run ruff check .
uv run mypy agos_context
uv build --no-sources

CI tests the wheel and source archive as external packages on Python 3.12 and 3.13.

Security

See SECURITY.md. Report vulnerabilities privately rather than opening a public issue.

License

Copyright 2026 I am Agos, Inc. Licensed under the Apache License, Version 2.0.