cleveragents-core/docs/api/acms.md

cleveragents.acms — Advanced Context Management System

The acms package provides UKO (Universal Knowledge Ontology) vocabulary support for the Advanced Context Management System. It contains Layer 2 paradigm vocabulary specializations and Layer 3 technology-specific vocabulary extensions, along with the DetailLevelMap inheritance mechanism for resolving named detail levels across the ontology hierarchy.

For the full ACMS pipeline and context assembly, see cleveragents.application.services. For the UKO runtime, see docs/reference/uko_runtime.md.

---

Overview

The acms package re-exports everything from cleveragents.acms.uko:

from cleveragents.acms import (
    # Vocabulary registry
    VocabularyRegistry,
    VocabularyClass,
    VocabularyProperty,
    ParadigmVocabulary,

    # Base UKO types
    UKOClass,
    UKOProperty,
    UKOVocabulary,
    Layer2Dependency,
    ProvenanceInfo,

    # Python vocabulary
    PYTHON_VOCABULARY,
    PYTHON_DETAIL_LEVELS,
    PythonClass,
    PythonFunction,
    PythonModule,
    PythonDecorator,
    PythonTypeStub,

    # TypeScript vocabulary
    TYPESCRIPT_VOCABULARY,
    TYPESCRIPT_DETAIL_LEVELS,
    TypeScriptClass,
    TypeScriptFunction,
    TypeScriptInterface,
    TypeScriptModule,

    # Rust vocabulary
    RUST_VOCABULARY,
    RUST_DETAIL_LEVELS,
    RustStruct,
    RustTrait,
    RustImpl,
    RustFunction,
    RustDeriveAttribute,

    # Java vocabulary
    JAVA_VOCABULARY,
    JAVA_DETAIL_LEVELS,
    JavaClass,
    JavaInterface,
    JavaMethod,
    JavaAnnotation,
    JavaCheckedException,

    # Detail level maps
    CODE_DETAIL_LEVEL_MAP,
    FUNC_DETAIL_LEVEL_MAP,
    OO_DETAIL_LEVEL_MAP,
    PROC_DETAIL_LEVEL_MAP,
    DetailLevelMapBuilder,

    # Utility functions
    build_detail_level_map,
    build_effective_map,
    get_func_vocabulary,
    get_oo_vocabulary,
    get_proc_vocabulary,
    resolve_detail_level,

    # Errors
    DuplicateVocabularyError,
)

---

Core Types

ProvenanceInfo

Provenance contract attached to every vocabulary class and property.

Field	Type	Description
source_spec	str	Specification section reference
issue_number	int	Forgejo issue number
introduced_version	str	Version when introduced (e.g. "3.6.0")
author	str	Author identifier
created_at	datetime	UTC creation timestamp (auto-set)

UKOClass

OWL class definition for a vocabulary.

Field	Type	Description
iri	str	Full IRI (must be a valid HTTP URI)
label	str	Human-readable label
comment	str	Description
parent_iris	list[str]	Parent class IRIs (inheritance)
provenance	ProvenanceInfo	Provenance metadata

UKOProperty

OWL property definition for a vocabulary.

Field	Type	Description
iri	str	Full IRI
label	str	Human-readable label
comment	str	Description
domain_iri	str	Domain class IRI
range_iri	str	Range class or datatype IRI
provenance	ProvenanceInfo	Provenance metadata

UKOVocabulary

Container for a vocabulary's classes, properties, and Layer 2 dependencies.

Field	Type	Description
namespace	str	Vocabulary namespace IRI
prefix	str	Namespace prefix (e.g. "uko-py")
classes	list[UKOClass]	All classes in this vocabulary
properties	list[UKOProperty]	All properties in this vocabulary
layer2_dependencies	list[Layer2Dependency]	Required Layer 2 vocabularies

---

Built-in Vocabularies

Python (PYTHON_VOCABULARY)

Layer 3 vocabulary for Python source code analysis.

Class	IRI suffix	Description
PythonModule	Module	A Python module (.py file)
PythonClass	Class	A Python class definition
PythonFunction	Function	A Python function or method
PythonDecorator	Decorator	A Python decorator
PythonTypeStub	TypeStub	A .pyi type stub

TypeScript (TYPESCRIPT_VOCABULARY)

Layer 3 vocabulary for TypeScript/JavaScript source code.

Class	Description
TypeScriptModule	A TypeScript module
TypeScriptClass	A TypeScript class
TypeScriptInterface	A TypeScript interface
TypeScriptFunction	A TypeScript function

Rust (RUST_VOCABULARY)

Layer 3 vocabulary for Rust source code.

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

Java (JAVA_VOCABULARY)

Layer 3 vocabulary for Java source code.

Class	Description
JavaClass	A Java class
JavaInterface	A Java interface
JavaMethod	A Java method
JavaAnnotation	A Java annotation
JavaCheckedException	A checked exception class

---

Detail Level Maps

Detail level maps control how much information is included when rendering a UKO node at a given depth. They follow a four-layer inheritance chain: Layer 3 → Layer 2 → Layer 1 → Layer 0.

Built-in Maps

Constant	Description
OO_DETAIL_LEVEL_MAP	Object-oriented paradigm levels (0–9)
FUNC_DETAIL_LEVEL_MAP	Functional paradigm levels
PROC_DETAIL_LEVEL_MAP	Procedural paradigm levels
CODE_DETAIL_LEVEL_MAP	Generic code levels

resolve_detail_level

Walk the inheritance chain to resolve a named detail level.

from cleveragents.acms import resolve_detail_level, PYTHON_DETAIL_LEVELS

level = resolve_detail_level("FULL_SOURCE", PYTHON_DETAIL_LEVELS)
# Returns the integer depth (0-9) for that level name

build_detail_level_map

Merge a parent map with child-level insertions.

from cleveragents.acms import build_detail_level_map, OO_DETAIL_LEVEL_MAP

custom_map = build_detail_level_map(
    parent=OO_DETAIL_LEVEL_MAP,
    insertions={"MY_LEVEL": 5},
)

---

VocabularyRegistry

Registry for all active UKO vocabularies.

from cleveragents.acms import VocabularyRegistry, PYTHON_VOCABULARY

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

Method	Description
register(vocab)	Register a vocabulary; raises DuplicateVocabularyError if prefix already registered
get(prefix)	Retrieve by prefix
list_vocabularies()	Return all registered vocabularies
get_class(iri)	Look up a class by full IRI across all vocabularies

---

Errors

Exception	Description
DuplicateVocabularyError	Raised when registering a vocabulary with an already-registered prefix

---

Related Documentation

• UKO Runtime — query interface, inference engine, persistence
• UKO Ontology — four-layer ontology specification
• UKO Layer 2 Vocabularies — paradigm vocabulary reference
• UKO Layer 3 Vocabularies — technology vocabulary reference
• ACMS Pipeline — context assembly pipeline
• Context Strategies — built-in retrieval strategies