cleveragents-core/docs/reference/uko_layer2_paradigm_vocabularies.md

UKO Layer 2 Paradigm Vocabularies

Overview

Layer 2 of the Unified Knowledge Ontology (UKO) refines the Layer 1 uko-code: domain with paradigm-specific specializations for three programming paradigms:

• Object-Oriented (uko-oo:) — classes, interfaces, methods, attributes
• Functional (uko-func:) — pure functions, type classes, monads
• Procedural (uko-proc:) — procedural functions, globals, headers, structs, macros

Each paradigm defines OWL classes that subclass Layer 1 or Layer 0 concepts, and extends the parent uko-code: DetailLevelMap with paradigm-specific named levels.

Based on docs/specification.md ~lines 42333-42422, 24923-25027.

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

Object-Oriented Vocabulary (uko-oo:)

Classes

Class	Superclasses	Description
uko-oo:Class	uko-code:TypeDefinition, uko:Container	An OO class that contains methods and attributes.
uko-oo:Interface	uko-code:TypeDefinition, uko:Boundary	An interface or abstract base class.
uko-oo:Method	uko-code:Callable	A method defined within a class.
uko-oo:Attribute	uko:Atom	A class or instance attribute.

Properties

Property	Domain	Range	subPropertyOf
uko-oo:inheritsFrom	uko-oo:Class	uko-oo:Class	uko:dependsOn
uko-oo:implements	uko-oo:Class	uko-oo:Interface	uko:dependsOn

DetailLevelMap Insertions

The OO map inserts two levels into the uko-code: base map:

Depth	Name	Origin	Content
3	CLASS_HIERARCHY	uko-oo:	Inheritance chains and interface implementations
7	VISIBILITY_ANNOTATED	uko-oo:	Public/protected/private modifiers

The full effective map with reassigned depths is documented in docs/specification.md ~lines 24991-25004.

Functional Vocabulary (uko-func:)

Classes

Class	Superclasses	Description
uko-func:PureFunction	uko-code:Callable	A pure function with no side effects.
uko-func:TypeClass	uko-code:TypeDefinition, uko:Boundary	A type class defining a set of operations for types.
uko-func:Monad	uko-code:TypeDefinition	A monadic type encapsulating computation context.

DetailLevelMap

Uses the same named levels as uko-code: without insertions.

Procedural Vocabulary (uko-proc:)

Classes

Class	Superclasses	Description
uko-proc:ProceduralFunction	uko-code:Callable	A procedural function declaration.
uko-proc:GlobalVariable	uko:Atom	A global variable declaration.
uko-proc:HeaderFile	uko:Container	A header file defining exported declarations.
uko-proc:StructDefinition	uko-code:TypeDefinition	A C-style struct type definition.
uko-proc:Macro	uko:Atom	A preprocessor macro definition.

DetailLevelMap

Uses the same named levels as uko-code: without insertions.

DetailLevelMap Inheritance

The inheritance chain resolves named levels by walking up the map hierarchy:

Layer 3 (uko-py:) -> Layer 2 (uko-oo:) -> Layer 1 (uko-code:) -> Layer 0 (uko:)

When a named level is requested, the system looks up the name in the most specific map first, then walks up to parent maps until a match is found. Integer depths are used directly (clamped to max_depth).

Insertion Mechanics

When a child map inserts a new named level (e.g., CLASS_HIERARCHY after MEMBER_LISTING), all subsequent levels shift upward by one to maintain consecutive integer numbering.

Python API

DetailLevelMapBuilder

from cleveragents.acms.uko.detail_level_maps import (
    CODE_DETAIL_LEVEL_MAP,
    DetailLevelMapBuilder,
)

builder = DetailLevelMapBuilder(CODE_DETAIL_LEVEL_MAP, "uko-oo:")
builder.insert_after("MEMBER_LISTING", "CLASS_HIERARCHY")
builder.insert_after("SIGNATURES_WITH_DOCS", "VISIBILITY_ANNOTATED")
oo_map = builder.build()

assert oo_map.resolve("CLASS_HIERARCHY") == 3
assert oo_map.resolve("FULL_SOURCE") == 11

VocabularyRegistry

from cleveragents.acms.uko.vocabularies import (
    get_oo_vocabulary,
    get_func_vocabulary,
    get_proc_vocabulary,
)
from cleveragents.acms.uko.vocabulary_registry import VocabularyRegistry

registry = VocabularyRegistry(
    vocabularies=(
        get_oo_vocabulary(),
        get_func_vocabulary(),
        get_proc_vocabulary(),
    )
)
oo = registry.get_by_prefix("uko-oo:")
assert oo is not None
assert oo.get_class("Class") is not None

Parent-Layer Dependencies

Layer 2 vocabularies reference these Layer 1 URIs via rdfs:subClassOf:

• https://cleveragents.ai/ontology/uko/code#TypeDefinition
• https://cleveragents.ai/ontology/uko/code#Callable

Layer 2 vocabularies also reference these Layer 0 URIs via rdfs:subClassOf or rdfs:subPropertyOf:

• https://cleveragents.ai/ontology/uko#Container — superclass of uko-oo:Class, uko-proc:HeaderFile
• https://cleveragents.ai/ontology/uko#Atom — superclass of uko-oo:Attribute, uko-proc:GlobalVariable, uko-proc:Macro
• https://cleveragents.ai/ontology/uko#Boundary — superclass of uko-oo:Interface, uko-func:TypeClass
• https://cleveragents.ai/ontology/uko#dependsOn — superproperty of uko-oo:inheritsFrom, uko-oo:implements

All URIs are defined in docs/ontology/uko.ttl and will be fully wired when the Layer 1 Python module (uko-code:) is implemented.

Limitations

• Layer 1 (uko-code:) Python module is not yet implemented; the Python code works standalone with the DetailLevelMap from crp.py.
• Turtle files are validated by the UKOLoader but not by a full OWL reasoner.
• The procedural vocabulary classes are inferred from the spec's rendering tables rather than explicit Turtle definitions.