cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [consistency] Inconsistent naming and structure between `vocabulary.py` and `vocabularies.py` #3157

New issue

Open

opened 2026-04-05 07:04:23 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 07:04:23 +00:00

Owner

Metadata

Branch: fix/backlog-uko-vocabulary-naming-consistency
Commit Message: fix(acms): reconcile UKO vocabulary class naming between vocabulary.py and vocabularies.py
Milestone: None (Backlog)
Parent Epic: #396

Background and Context

The files src/cleveragents/acms/uko/vocabulary.py and src/cleveragents/acms/uko/vocabularies.py define similar data structures with inconsistent naming and structure. This increases cognitive load for developers and creates potential for subtle bugs if the two representations are used interchangeably. Any developer working with UKO will encounter both files.

Current Behavior

vocabularies.py defines VocabularyClass, VocabularyProperty, and ParadigmVocabulary.
vocabulary.py defines UKOClass, UKOProperty, and UKOVocabulary.

The structures are very similar, but have different field names for the same concepts. For example, VocabularyClass has parent_uris, while UKOClass has subclass_of.

Evidence:

vocabularies.py:

class VocabularyClass(BaseModel, frozen=True):
    uri: str = Field(
        ...,
        min_length=1,
        description="Full IRI of this OWL class",
    )
    # ...
    parent_uris: tuple[str, ...] = Field(
        default=(),
        description="rdfs:subClassOf parent IRIs",
    )

vocabulary.py:

class UKOClass(BaseModel):
    uri: str = Field(..., min_length=1, description="Full IRI of the class.")
    # ...
    subclass_of: tuple[str, ...] = Field(
        default=(),
        description="Parent class URIs (rdfs:subClassOf).",
    )

Expected Behavior

There should be a single, consistent set of classes for representing vocabularies, classes, and properties within the UKO ACMS pipeline.

Subtasks

Audit all usages of VocabularyClass, VocabularyProperty, ParadigmVocabulary (from vocabularies.py) across the codebase
Audit all usages of UKOClass, UKOProperty, UKOVocabulary (from vocabulary.py) across the codebase
Determine canonical representation (the classes in vocabulary.py appear more recent and feature-complete)
Deprecate and replace vocabularies.py classes with the canonical set from vocabulary.py
Update all import sites to use the canonical classes
Add deprecation warnings or remove vocabularies.py entirely
Tests (Behave): Add/update scenarios for vocabulary class consistency
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A single, consistent set of classes represents UKO vocabularies, classes, and properties — no duplicate or conflicting implementations remain.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Supporting Information

Severity: Medium — increased cognitive load, potential for subtle bugs if representations are used interchangeably.
Location: src/cleveragents/acms/uko/vocabulary.py and src/cleveragents/acms/uko/vocabularies.py
Affected classes: VocabularyClass vs UKOClass, VocabularyProperty vs UKOProperty, ParadigmVocabulary vs UKOVocabulary
Suggested Fix: Refactor to use a single set of classes. The classes in vocabulary.py seem more recent and feature-complete; deprecate and replace those in vocabularies.py.
Originally reported by: ca-bug-hunter (Bug Hunting supervisor)

Backlog note: This issue was discovered during autonomous operation
on milestone v3.4.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/backlog-uko-vocabulary-naming-consistency` - **Commit Message**: `fix(acms): reconcile UKO vocabulary class naming between vocabulary.py and vocabularies.py` - **Milestone**: None (Backlog) - **Parent Epic**: #396 ## Background and Context The files `src/cleveragents/acms/uko/vocabulary.py` and `src/cleveragents/acms/uko/vocabularies.py` define similar data structures with inconsistent naming and structure. This increases cognitive load for developers and creates potential for subtle bugs if the two representations are used interchangeably. Any developer working with UKO will encounter both files. ## Current Behavior `vocabularies.py` defines `VocabularyClass`, `VocabularyProperty`, and `ParadigmVocabulary`. `vocabulary.py` defines `UKOClass`, `UKOProperty`, and `UKOVocabulary`. The structures are very similar, but have different field names for the same concepts. For example, `VocabularyClass` has `parent_uris`, while `UKOClass` has `subclass_of`. **Evidence:** `vocabularies.py`: ```python class VocabularyClass(BaseModel, frozen=True): uri: str = Field( ..., min_length=1, description="Full IRI of this OWL class", ) # ... parent_uris: tuple[str, ...] = Field( default=(), description="rdfs:subClassOf parent IRIs", ) ``` `vocabulary.py`: ```python class UKOClass(BaseModel): uri: str = Field(..., min_length=1, description="Full IRI of the class.") # ... subclass_of: tuple[str, ...] = Field( default=(), description="Parent class URIs (rdfs:subClassOf).", ) ``` ## Expected Behavior There should be a single, consistent set of classes for representing vocabularies, classes, and properties within the UKO ACMS pipeline. ## Subtasks - [ ] Audit all usages of `VocabularyClass`, `VocabularyProperty`, `ParadigmVocabulary` (from `vocabularies.py`) across the codebase - [ ] Audit all usages of `UKOClass`, `UKOProperty`, `UKOVocabulary` (from `vocabulary.py`) across the codebase - [ ] Determine canonical representation (the classes in `vocabulary.py` appear more recent and feature-complete) - [ ] Deprecate and replace `vocabularies.py` classes with the canonical set from `vocabulary.py` - [ ] Update all import sites to use the canonical classes - [ ] Add deprecation warnings or remove `vocabularies.py` entirely - [ ] Tests (Behave): Add/update scenarios for vocabulary class consistency - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A single, consistent set of classes represents UKO vocabularies, classes, and properties — no duplicate or conflicting implementations remain. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. ## Supporting Information - **Severity**: Medium — increased cognitive load, potential for subtle bugs if representations are used interchangeably. - **Location**: `src/cleveragents/acms/uko/vocabulary.py` and `src/cleveragents/acms/uko/vocabularies.py` - **Affected classes**: `VocabularyClass` vs `UKOClass`, `VocabularyProperty` vs `UKOProperty`, `ParadigmVocabulary` vs `UKOVocabulary` - **Suggested Fix**: Refactor to use a single set of classes. The classes in `vocabulary.py` seem more recent and feature-complete; deprecate and replace those in `vocabularies.py`. - Originally reported by: ca-bug-hunter (Bug Hunting supervisor) > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 07:07:45 +00:00

#396 Epic: ACMS Context Pipeline

freemo added the

MoSCoW

Could have

label

2026-04-05 07:11:40 +00:00

freemo commented

2026-04-05 07:11:40 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Backlog (keeping existing)
Milestone: v3.6.0 (code quality/consistency improvement)
MoSCoW: Could Have — naming inconsistency between vocabulary.py and vocabularies.py is a code quality concern but does not affect runtime behavior. Consolidation is desirable but not blocking.
Parent Epic: #396 (ACMS Context Pipeline)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Backlog (keeping existing) - **Milestone**: v3.6.0 (code quality/consistency improvement) - **MoSCoW**: Could Have — naming inconsistency between vocabulary.py and vocabularies.py is a code quality concern but does not affect runtime behavior. Consolidation is desirable but not blocking. - **Parent Epic**: #396 (ACMS Context Pipeline) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.6.0 milestone

2026-04-05 07:11:40 +00:00

freemo referenced this issue

2026-04-05 07:37:42 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo modified the milestone from v3.6.0 to v3.7.0

2026-04-05 07:43:26 +00:00

freemo commented

2026-04-05 07:45:33 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified ✅
Priority: Backlog (unchanged)
Milestone: v3.7.0 (assigned)
MoSCoW: Could Have — Naming inconsistency between vocabulary.py and vocabularies.py is a valid code quality concern but doesn't affect functionality. This is a refactoring task that can be deferred.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified ✅ - **Priority**: Backlog (unchanged) - **Milestone**: v3.7.0 (assigned) - **MoSCoW**: Could Have — Naming inconsistency between `vocabulary.py` and `vocabularies.py` is a valid code quality concern but doesn't affect functionality. This is a refactoring task that can be deferred. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 08:07:05 +00:00

[CA-AUTO] Project Owner — project-owner-1 — Session Tracker #2793