cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

feat(acms): implement UKO Layer 3 Technology Vocabularies (uko-py, uko-ts, uko-rs, uko-java)
CI / benchmark-publish (pull_request) Has been skipped
Details
CI / lint (pull_request) Successful in 19s
Details
CI / build (pull_request) Successful in 27s
Details
CI / quality (pull_request) Successful in 29s
Details
CI / security (pull_request) Successful in 41s
Details
CI / typecheck (pull_request) Successful in 45s
Details
CI / e2e_tests (pull_request) Successful in 1m29s
Details
CI / unit_tests (pull_request) Successful in 3m19s
Details
CI / integration_tests (pull_request) Successful in 3m30s
Details
CI / docker (pull_request) Successful in 54s
Details
CI / coverage (pull_request) Successful in 6m8s
Details
CI / benchmark-regression (pull_request) Successful in 38m9s
Details

Browse Source 
Implement Layer 3 technology-specific UKO vocabulary extensions for Python,
TypeScript, Rust, and Java with language-specific classes, properties, and
DetailLevelMap insertions.

- 4 OWL/Turtle ontology files with language-specific semantic classes
- DetailLevelMap insertion logic with correct integer reassignment
- Provenance contract (5 required fields per spec)
- Full 4-layer chain resolution (Layer 3 -> Layer 2 -> Layer 1 -> Layer 0)
- Comprehensive Behave test suite (63 scenarios)

ISSUES CLOSED: #576
This commit is contained in:
Hamza Khyari
2026-03-10 00:28:06 +00:00
committed by Forgejo
parent 3b6b1d2414
commit 89eaee008d
19 changed files with 4191 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/uko_layer3_technology_vocabularies.md
+173
View File
@@ -0,0 +1,173 @@
# UKO Layer 3 Technology Vocabularies
## Overview
Layer 3 of the Unified Knowledge Ontology (UKO) extends Layer 2 paradigm
vocabularies (or Layer 1 directly) with technology-specific semantic
refinements for four programming languages:
- **Python** (`uko-py:`) -- decorators, `.pyi` type stubs, test associations
- **TypeScript** (`uko-ts:`) -- export markers, ambient types, generics, mapped/conditional types
- **Rust** (`uko-rs:`) -- visibility, lifetimes, trait bounds, derive macros, unsafe markers
- **Java** (`uko-java:`) -- package visibility, modifiers, annotations, checked exceptions
Each vocabulary defines OWL classes, properties, Layer 2 dependencies, and
optional DetailLevelMap insertions per `docs/specification.md` ~lines 44405-44420.
## Namespace Prefixes
| Prefix | IRI | Layer |
|--------|-----|-------|
| `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 |
## Python Vocabulary (`uko-py:`)
### Classes
| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-py:PythonModule` | `uko-code:Module` | A Python module (`.py` file). |
| `uko-py:PythonClass` | `uko-oo:Class` | A Python class definition. |
| `uko-py:PythonFunction` | `uko-oo:Method` | A Python function or method. |
| `uko-py:PythonDecorator` | `uko-code:TypeDefinition` | A decorator chain entry. |
| `uko-py:PythonTypeStub` | `uko-code:TypeDefinition` | `.pyi` stub type annotation. |
### Properties
| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-py:hasDecorator` | PythonFunction, PythonClass | PythonDecorator | ObjectProperty |
| `uko-py:hasTypeStub` | PythonModule, PythonClass, PythonFunction | PythonTypeStub | ObjectProperty |
| `uko-py:hasTest` | PythonFunction, PythonClass | PythonFunction | ObjectProperty |
| `uko-py:decoratorName` | PythonDecorator | `xsd:string` | DatatypeProperty |
| `uko-py:stubAnnotation` | PythonTypeStub | `xsd:string` | DatatypeProperty |
### DetailLevelMap Insertions
Python inserts 3 levels into the OO parent map, producing a 15-level effective map:
| Depth | Name | Description |
|-------|------|-------------|
| 7 | `DECORATED_SIGNATURES` | Decorator chains (`@property`, `@staticmethod`, custom). |
| 11 | `TYPE_STUBS` | Type annotations from `.pyi` stub files. |
| 14 | `WITH_TESTS` | Full source + associated test cases. |
## TypeScript Vocabulary (`uko-ts:`)
### Classes
| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-ts:TypeScriptModule` | `uko-code:Module` | A TypeScript module (`.ts`/`.tsx`). |
| `uko-ts:TypeScriptClass` | `uko-oo:Class` | A TypeScript class. |
| `uko-ts:TypeScriptInterface` | `uko-oo:Interface` | A TypeScript interface (generics, mapped/conditional). |
| `uko-ts:TypeScriptFunction` | `uko-oo:Method` | A TypeScript function or method. |
### Properties
| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-ts:exportKind` | TypeScriptClass, TypeScriptInterface, TypeScriptFunction, TypeScriptModule | `xsd:string` | DatatypeProperty |
| `uko-ts:isAmbient` | TypeScriptClass, TypeScriptInterface, TypeScriptFunction | `xsd:boolean` | DatatypeProperty |
| `uko-ts:genericParameters` | TypeScriptClass, TypeScriptInterface, TypeScriptFunction | `xsd:string` | DatatypeProperty |
| `uko-ts:isMappedType` | TypeScriptInterface | `xsd:boolean` | DatatypeProperty |
| `uko-ts:isConditionalType` | TypeScriptInterface | `xsd:boolean` | DatatypeProperty |
| `uko-ts:implementsInterface` | TypeScriptClass | TypeScriptInterface | ObjectProperty |
### DetailLevelMap Insertions
TypeScript extends at the SIGNATURES level with no new depth insertions (12-level identity map).
## Rust Vocabulary (`uko-rs:`)
### Classes
| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-rs:RustStruct` | `uko-oo:Class` | A Rust struct definition. |
| `uko-rs:RustTrait` | `uko-oo:Interface` | A Rust trait definition. |
| `uko-rs:RustImpl` | `uko-code:TypeDefinition` | A Rust impl block. |
| `uko-rs:RustFunction` | `uko-oo:Method` | A Rust function or method. |
| `uko-rs:RustDeriveAttribute` | `uko-code:TypeDefinition` | A `#[derive(...)]` macro attribute. |
### Properties
| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-rs:visibility` | RustStruct, RustTrait, RustFunction | `xsd:string` | DatatypeProperty |
| `uko-rs:lifetimeParameters` | RustStruct, RustImpl, RustFunction, RustTrait | `xsd:string` | DatatypeProperty |
| `uko-rs:traitBounds` | RustStruct, RustFunction, RustImpl | `xsd:string` | DatatypeProperty |
| `uko-rs:isUnsafe` | RustFunction, RustImpl, RustTrait | `xsd:boolean` | DatatypeProperty |
| `uko-rs:deriveTraits` | RustDeriveAttribute | `xsd:string` | DatatypeProperty |
| `uko-rs:mustUse` | RustStruct, RustFunction | `xsd:boolean` | DatatypeProperty |
| `uko-rs:hasDerive` | RustStruct | RustDeriveAttribute | ObjectProperty |
| `uko-rs:implementsTrait` | RustImpl | RustTrait | ObjectProperty |
### DetailLevelMap Insertions
Rust extends at the SIGNATURES level with no new depth insertions (12-level identity map).
## Java Vocabulary (`uko-java:`)
### Classes
| Class | Superclass | Description |
|-------|-----------|-------------|
| `uko-java:JavaClass` | `uko-oo:Class` | A Java class definition. |
| `uko-java:JavaInterface` | `uko-oo:Interface` | A Java interface. |
| `uko-java:JavaMethod` | `uko-oo:Method` | A Java method. |
| `uko-java:JavaAnnotation` | `uko-code:TypeDefinition` | A Java annotation entry. |
| `uko-java:JavaCheckedException` | `uko-code:TypeDefinition` | A checked exception declaration. |
### Properties
| Property | Domain | Range | Type |
|----------|--------|-------|------|
| `uko-java:packageVisibility` | JavaClass, JavaInterface, JavaMethod | `xsd:string` | DatatypeProperty |
| `uko-java:isFinal` | JavaClass, JavaMethod | `xsd:boolean` | DatatypeProperty |
| `uko-java:isAbstract` | JavaClass, JavaMethod | `xsd:boolean` | DatatypeProperty |
| `uko-java:isSealed` | JavaClass, JavaInterface | `xsd:boolean` | DatatypeProperty |
| `uko-java:hasAnnotation` | JavaClass, JavaInterface, JavaMethod | JavaAnnotation | ObjectProperty |
| `uko-java:annotationName` | JavaAnnotation | `xsd:string` | DatatypeProperty |
| `uko-java:throwsException` | JavaMethod | JavaCheckedException | ObjectProperty |
| `uko-java:exceptionClass` | JavaCheckedException | `xsd:string` | DatatypeProperty |
### DetailLevelMap Insertions
Java extends at the SIGNATURES level with no new depth insertions (12-level identity map).
## Shared Base Types
All Layer 3 vocabularies use shared types from `vocabulary.py`:
| Type | Description |
|------|-------------|
| `ProvenanceInfo` | Frozen Pydantic model with 2 required fields (`source_resource`, `source_path`) and 3 defaulted fields (`source_range`, `valid_from`, `is_current`). |
| `UKOClass` | Frozen OWL class definition (`uri`, `label`, `comment`, `subclass_of`, `provenance`). |
| `UKOProperty` | Frozen OWL property definition (`uri`, `label`, `comment`, `domain`, `range_uri`, `is_object_property`, `provenance`). |
| `Layer2Dependency` | Declared dependency on a Layer 1/2 URI (`uri`, `layer`, `prefix`, `description`). |
| `UKOVocabulary` | Container aggregating classes, properties, deps, inserted levels, and optional `provenance`. |
## Utility Functions
| Function | Description |
|----------|-------------|
| `build_detail_level_map(parent_levels, insertions)` | Merge parent + child insertions with consecutive integer re-numbering. |
| `resolve_detail_level(name, levels, parent_levels=None)` | Look up a named level in `levels`, falling back to `parent_levels`. |
## Source Files
| File | Description |
|------|-------------|
| `src/cleveragents/acms/uko/vocabulary.py` | Shared base types and utility functions. |
| `src/cleveragents/acms/uko/layer3_py.py` | Python vocabulary definitions. |
| `src/cleveragents/acms/uko/layer3_ts.py` | TypeScript vocabulary definitions. |
| `src/cleveragents/acms/uko/layer3_rs.py` | Rust vocabulary definitions. |
| `src/cleveragents/acms/uko/layer3_java.py` | Java vocabulary definitions. |
| `docs/ontology/uko-py.ttl` | Python OWL/Turtle ontology. |
| `docs/ontology/uko-ts.ttl` | TypeScript OWL/Turtle ontology. |
| `docs/ontology/uko-rs.ttl` | Rust OWL/Turtle ontology. |
| `docs/ontology/uko-java.ttl` | Java OWL/Turtle ontology. |