temp/docs/api/acms.md

cleveragents.acms — Advanced Context Management System

The acms package implements the Advanced Context Management System (ACMS), providing UKO (Universal Knowledge Ontology) vocabulary extensions for context assembly. It defines Layer 2 paradigm vocabularies (Object-Oriented, Functional, Procedural) and Layer 3 technology-specific vocabulary extensions for Python, TypeScript, Rust, and Java.

See ADR-014 for the design rationale and docs/reference/acms.md for the full ACMS reference.

---

Overview

The ACMS vocabulary system is organized in four layers:

Layer	Prefix	Description
0	uko:	Universal foundation — base classes and properties
1	uko-code:	Code-level abstractions
2	uko-oo:, uko-func:, uko-proc:	Paradigm specializations
3	uko-py:, uko-ts:, uko-rs:, uko-java:	Technology-specific extensions

from cleveragents.acms import (
    # Layer 2 paradigm vocabularies
    get_oo_vocabulary,
    get_func_vocabulary,
    get_proc_vocabulary,
    # Layer 3 technology vocabularies
    PYTHON_VOCABULARY,
    TYPESCRIPT_VOCABULARY,
    RUST_VOCABULARY,
    JAVA_VOCABULARY,
    # Detail level resolution
    resolve_detail_level,
    build_detail_level_map,
    build_effective_map,
    # Registry
    VocabularyRegistry,
)

# Resolve a detail level for a Python class
oo_map = get_oo_vocabulary().detail_level_map
py_map = PYTHON_VOCABULARY.detail_level_map
effective = build_effective_map(py_map, oo_map)
level = resolve_detail_level("PythonClass", effective)

---

Base Vocabulary Types

UKOVocabulary

Abstract base class for all UKO vocabulary definitions.

Attribute	Type	Description
namespace	str	Namespace prefix (e.g. uko-py:).
iri	str	Full IRI for the namespace.
layer	int	Ontology layer (0–3).
classes	list[UKOClass]	Classes defined in this vocabulary.
properties	list[UKOProperty]	Properties defined in this vocabulary.
detail_level_map	DetailLevelMap	Maps class names to detail levels.

UKOClass

Represents a class in the UKO ontology.

Attribute	Type	Description
name	str	Class name (e.g. PythonClass).
iri	str	Full IRI for the class.
parent	str | None	Parent class IRI (for inheritance).
description	str	Human-readable description.

UKOProperty

Represents a property in the UKO ontology.

Attribute	Type	Description
name	str	Property name.
iri	str	Full IRI for the property.
domain	str	Domain class IRI.
range	str	Range class or datatype IRI.
description	str	Human-readable description.

Layer2Dependency

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

Layer2Dependency(
    layer2_namespace="uko-oo:",
    layer2_iri="https://cleveragents.ai/ontology/uko/oo#",
)

ProvenanceInfo

Provenance metadata attached to vocabulary definitions.

Attribute	Type	Description
source	str	Source document or specification reference.
version	str	Version when this vocabulary was introduced.

---

Layer 2 — Paradigm Vocabularies

ParadigmVocabulary

Extends UKOVocabulary for Layer 2 paradigm specializations.

VocabularyClass

Extends UKOClass with paradigm-specific metadata.

VocabularyProperty

Extends UKOProperty with paradigm-specific metadata.

Factory Functions

from cleveragents.acms import get_oo_vocabulary, get_func_vocabulary, get_proc_vocabulary

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

---

Layer 3 — Technology Vocabularies

Python (uko-py:)

from cleveragents.acms import (
    PYTHON_VOCABULARY,
    PYTHON_DETAIL_LEVELS,
    PythonClass,
    PythonFunction,
    PythonModule,
    PythonDecorator,
    PythonTypeStub,
)

Class	Description
PythonClass	Python class definition (class Foo:).
PythonFunction	Python function or method (def foo():).
PythonModule	Python module (.py file).
PythonDecorator	Python decorator (@decorator).
PythonTypeStub	Python type stub (.pyi file).

TypeScript (uko-ts:)

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

Class	Description
TypeScriptClass	TypeScript class definition.
TypeScriptFunction	TypeScript function or method.
TypeScriptInterface	TypeScript interface declaration.
TypeScriptModule	TypeScript module (.ts / .tsx file).

Rust (uko-rs:)

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

Class	Description
RustStruct	Rust struct definition.
RustTrait	Rust trait definition.
RustImpl	Rust impl block.
RustFunction	Rust function or method.
RustDeriveAttribute	Rust #[derive(...)] attribute.

Java (uko-java:)

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

Class	Description
JavaClass	Java class definition.
JavaInterface	Java interface declaration.
JavaMethod	Java method definition.
JavaAnnotation	Java annotation type.
JavaCheckedException	Java checked exception class.

---

Detail Level System

Detail levels control how much information is included when a resource is indexed into the knowledge graph. The system uses a hierarchical inheritance mechanism: Layer 3 maps inherit from Layer 2, which inherit from Layer 1.

Pre-built Maps

from cleveragents.acms import (
    CODE_DETAIL_LEVEL_MAP,   # Layer 1 — base code detail levels
    OO_DETAIL_LEVEL_MAP,     # Layer 2 — OO paradigm detail levels
    FUNC_DETAIL_LEVEL_MAP,   # Layer 2 — Functional paradigm detail levels
    PROC_DETAIL_LEVEL_MAP,   # Layer 2 — Procedural paradigm detail levels
    PYTHON_DETAIL_LEVELS,    # Layer 3 — Python detail levels
    TYPESCRIPT_DETAIL_LEVELS,# Layer 3 — TypeScript detail levels
    RUST_DETAIL_LEVELS,      # Layer 3 — Rust detail levels
    JAVA_DETAIL_LEVELS,      # Layer 3 — Java detail levels
)

resolve_detail_level

level = resolve_detail_level(class_name: str, detail_level_map: dict) -> int

Resolve the detail level for a named class using the provided map. Returns the level integer (higher = more detail).

build_detail_level_map

map = build_detail_level_map(vocabulary: UKOVocabulary) -> dict[str, int]

Build a detail level map from a vocabulary's class definitions.

build_effective_map

effective = build_effective_map(child_map: dict, parent_map: dict) -> dict[str, int]

Merge a child map with a parent map, with child entries taking precedence. Used to resolve Layer 3 detail levels against their Layer 2 parents.

DetailLevelMapBuilder

Fluent builder for constructing custom detail level maps:

from cleveragents.acms import DetailLevelMapBuilder

custom_map = (
    DetailLevelMapBuilder()
    .add("MyClass", level=3)
    .add("MyFunction", level=2)
    .build()
)

---

VocabularyRegistry

Global registry for all UKO vocabulary instances.

from cleveragents.acms import VocabularyRegistry

registry = VocabularyRegistry()
registry.register(PYTHON_VOCABULARY)
vocab = registry.get("uko-py:")
all_vocabs = registry.list_all()

Methods

Method	Signature	Description
register	(vocab: UKOVocabulary) → None	Register a vocabulary. Raises DuplicateVocabularyError if already registered.
get	(namespace: str) → UKOVocabulary | None	Look up by namespace prefix.
list_all	() → list[UKOVocabulary]	Return all registered vocabularies.

DuplicateVocabularyError

Raised when attempting to register a vocabulary with a namespace that is already registered.

---

Related Documentation

• ADR-014 Context Management (ACMS)
• ACMS Reference
• ACMS Context Strategies
• UKO Ontology
• UKO Runtime
• UKO Layer 2 Paradigm Vocabularies
• UKO Layer 3 Technology Vocabularies
• UKO Provenance Tracking