cleveragents-core/docs/api/acms.md

cleveragents.acms — Advanced Context Management System

The acms package implements the Universal Knowledge Ontology (UKO) vocabulary support for the Advanced Context Management System. It provides a four-layer ontology hierarchy for representing code semantics across multiple programming languages, enabling actors to reason about large codebases with structured, budget-constrained context views.

See ADR-014 for the design rationale and docs/modules/uko-provenance.md for provenance tracking details.

---

Architecture Overview

The UKO is organized into four layers:

Layer	Scope	Examples
Layer 0	Universal primitives	Container, Atom, Boundary, dependsOn
Layer 1	General code domain	TypeDefinition, Callable
Layer 2	Programming paradigms	uko-oo:, uko-func:, uko-proc:
Layer 3	Language-specific	uko-py:, uko-ts:, uko-rs:, uko-java:

---

Namespace Prefixes

Prefix	IRI	Layer
uko-oo:	https://cleveragents.ai/ontology/uko/oo#	2
uko-func:	https://cleveragents.ai/ontology/uko/func#	2
uko-proc:	https://cleveragents.ai/ontology/uko/proc#	2
uko-py:	https://cleveragents.ai/ontology/uko/py#	3
uko-ts:	https://cleveragents.ai/ontology/uko/ts#	3
uko-rs:	https://cleveragents.ai/ontology/uko/rs#	3
uko-java:	https://cleveragents.ai/ontology/uko/java#	3

---

Core Types

ProvenanceInfo

from cleveragents.acms import ProvenanceInfo

class ProvenanceInfo(BaseModel):
    source_resource: str        # IRI of the source resource
    valid_from: datetime        # When this triple became valid
    is_current: bool            # Whether this is the current revision
    created_by: str             # Agent or process that created this
    revision_chain: list[str]   # Ordered list of prior revision IRIs

Provenance contract attached to every typed triple in the UKO graph. Enables temporal queries and point-in-time ontology state reconstruction.

---

UKOClass

from cleveragents.acms import UKOClass

class UKOClass(BaseModel):
    uri: str                    # Fully-qualified OWL class URI
    label: str                  # Human-readable label
    parent_uri: str | None      # rdfs:subClassOf parent URI
    description: str = ""       # Optional description

Represents an OWL class definition within a UKO vocabulary.

---

UKOProperty

from cleveragents.acms import UKOProperty

class UKOProperty(BaseModel):
    uri: str                    # Fully-qualified OWL property URI
    label: str                  # Human-readable label
    domain_uri: str             # rdfs:domain class URI
    range_uri: str              # rdfs:range class URI
    parent_uri: str | None      # rdfs:subPropertyOf parent URI

Represents an OWL object property definition within a UKO vocabulary.

---

UKOVocabulary

from cleveragents.acms import UKOVocabulary

class UKOVocabulary(BaseModel):
    prefix: str                         # Namespace prefix (e.g. "uko-py:")
    iri: str                            # Namespace IRI
    classes: tuple[UKOClass, ...]       # OWL classes in this vocabulary
    properties: tuple[UKOProperty, ...]  # OWL properties in this vocabulary
    layer2_deps: tuple[Layer2Dependency, ...]  # Layer 2 dependencies

Container for a complete UKO vocabulary (classes + properties + dependencies).

---

Layer2Dependency

from cleveragents.acms import Layer2Dependency

class Layer2Dependency(BaseModel):
    iri: str    # Layer 2 vocabulary IRI this vocabulary depends on

Declares a dependency from a Layer 3 vocabulary on a Layer 2 paradigm vocabulary.

---

Layer 2 — Paradigm Vocabularies

ParadigmVocabulary

from cleveragents.acms import ParadigmVocabulary

class ParadigmVocabulary(BaseModel):
    prefix: str                         # e.g. "uko-oo:"
    iri: str                            # Namespace IRI
    classes: tuple[VocabularyClass, ...]
    properties: tuple[VocabularyProperty, ...]

Immutable (frozen) Pydantic model for a Layer 2 paradigm vocabulary.

Built-in paradigm vocabularies:

from cleveragents.acms import get_oo_vocabulary, get_func_vocabulary, get_proc_vocabulary

oo_vocab = get_oo_vocabulary()      # Object-Oriented paradigm (uko-oo:)
func_vocab = get_func_vocabulary()  # Functional paradigm (uko-func:)
proc_vocab = get_proc_vocabulary()  # Procedural paradigm (uko-proc:)

---

VocabularyRegistry

from cleveragents.acms import VocabularyRegistry, DuplicateVocabularyError

registry = VocabularyRegistry(vocabularies=(get_oo_vocabulary(),))

# Register a vocabulary
registry.register(get_func_vocabulary())

# Look up by prefix
vocab = registry.get_by_prefix("uko-oo:")

# Look up by IRI
vocab = registry.get_by_iri("https://cleveragents.ai/ontology/uko/oo#")

# List all registered prefixes
prefixes = registry.list_prefixes()

# List all vocabularies
all_vocabs = registry.list_all()

# Unregister
registry.unregister("uko-oo:")

Thread safety: VocabularyRegistry is not thread-safe. Populate once during module initialisation under the GIL; do not mutate from multiple threads.

Raises: DuplicateVocabularyError if a vocabulary with the same prefix or IRI is already registered.

---

Detail Level Maps

Detail level maps control how much semantic detail is included in context views for each code construct. They form an inheritance chain: Layer 3 maps extend Layer 2 maps, which extend Layer 1 maps.

Built-in Maps

from cleveragents.acms import (
    CODE_DETAIL_LEVEL_MAP,   # Layer 1 general code domain
    OO_DETAIL_LEVEL_MAP,     # Layer 2 Object-Oriented
    FUNC_DETAIL_LEVEL_MAP,   # Layer 2 Functional
    PROC_DETAIL_LEVEL_MAP,   # Layer 2 Procedural
)

Each map is a DetailLevelMap with a .levels dict mapping level names to integer depth values.

DetailLevelMapBuilder

from cleveragents.acms import DetailLevelMapBuilder

builder = DetailLevelMapBuilder(parent=OO_DETAIL_LEVEL_MAP)
builder.insert("uko-py:decorator", depth=3)
builder.insert("uko-py:type_stub", depth=4)
py_map = builder.build()

Builds a new DetailLevelMap by inserting level entries into a parent map.

build_detail_level_map

from cleveragents.acms import build_detail_level_map

level_map = build_detail_level_map(
    parent=OO_DETAIL_LEVEL_MAP,
    insertions=[("uko-py:decorator", 3), ("uko-py:type_stub", 4)],
)

Functional alternative to DetailLevelMapBuilder.

build_effective_map

from cleveragents.acms import build_effective_map

effective = build_effective_map(
    parent=OO_DETAIL_LEVEL_MAP,
    child=PYTHON_DETAIL_LEVELS,
)

Merges a parent map and a child map into a single effective map, with child entries taking precedence over parent entries.

resolve_detail_level

from cleveragents.acms import resolve_detail_level

depth = resolve_detail_level(
    name="uko-py:function",
    maps=[PYTHON_DETAIL_LEVELS, OO_DETAIL_LEVEL_MAP, CODE_DETAIL_LEVEL_MAP],
)

Walks the inheritance chain (Layer 3 → Layer 2 → Layer 1) to resolve a named detail level to its integer depth. Returns None if not found in any map.

---

Layer 3 — Language Vocabularies

Python (uko-py:)

from cleveragents.acms import (
    PYTHON_VOCABULARY,    # ParadigmVocabulary for Python
    PYTHON_DETAIL_LEVELS, # DetailLevelMap for Python
    PythonModule,
    PythonClass,
    PythonFunction,
    PythonDecorator,
    PythonTypeStub,
)

Class	Parent	Description
PythonModule	uko-oo:Module	A Python .py module
PythonClass	uko-oo:Class	A Python class definition
PythonFunction	uko-oo:Method	A Python function or method
PythonDecorator	uko-oo:Annotation	A Python decorator
PythonTypeStub	uko-oo:Interface	A .pyi type stub

TypeScript (uko-ts:)

from cleveragents.acms import (
    TYPESCRIPT_VOCABULARY,
    TYPESCRIPT_DETAIL_LEVELS,
    TypeScriptModule,
    TypeScriptClass,
    TypeScriptFunction,
    TypeScriptInterface,
)

Rust (uko-rs:)

from cleveragents.acms import (
    RUST_VOCABULARY,
    RUST_DETAIL_LEVELS,
    RustStruct,
    RustTrait,
    RustImpl,
    RustFunction,
    RustDeriveAttribute,
)

Java (uko-java:)

from cleveragents.acms import (
    JAVA_VOCABULARY,
    JAVA_DETAIL_LEVELS,
    JavaClass,
    JavaInterface,
    JavaMethod,
    JavaAnnotation,
    JavaCheckedException,
)

---

Usage Example

from cleveragents.acms import (
    VocabularyRegistry,
    get_oo_vocabulary,
    get_func_vocabulary,
    PYTHON_VOCABULARY,
    PYTHON_DETAIL_LEVELS,
    OO_DETAIL_LEVEL_MAP,
    resolve_detail_level,
)

# Build a registry with Layer 2 paradigm vocabularies
registry = VocabularyRegistry(
    vocabularies=(
        get_oo_vocabulary(),
        get_func_vocabulary(),
    )
)

# Resolve a detail level for a Python function
depth = resolve_detail_level(
    name="uko-py:function",
    maps=[PYTHON_DETAIL_LEVELS, OO_DETAIL_LEVEL_MAP],
)
print(f"Python function detail depth: {depth}")

# Look up a vocabulary by prefix
oo_vocab = registry.get_by_prefix("uko-oo:")
print(f"OO vocabulary has {len(oo_vocab.classes)} classes")

---

Note: The ACMS module is internal to the context assembly pipeline. Direct use is only needed when implementing custom context strategies. For typical usage, configure context policies via agents context CLI commands — see the Specification for details.