Metadata-Version: 2.4
Name: agos-context
Version: 0.1.1
Summary: A deterministic bounded context graph kernel
Author: I am Agos, Inc.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/iamagos/agos-context
Project-URL: Repository, https://github.com/iamagos/agos-context
Project-URL: Issues, https://github.com/iamagos/agos-context/issues
Keywords: agents,context,graphs,provenance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic<3,>=2.13.3
Dynamic: license-file

# agos-context

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

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

The package owns four semantics:

| Module | Meaning |
| --- | --- |
| `graph` | Stable addresses, exact revisions, owner assertions, bounds, omissions, and Slice identity. |
| `predicate` | Typed owner-defined construction of lawful links. |
| `compile` | Explicit retention order and deterministic bounded compilation. |
| `traversal` | Byte- and count-bounded neighborhoods, directed paths, and exact source closure. |

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

## Install

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

## Example

```python
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`:

```text
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

```bash
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](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.
