AGENTS.md@src/gnn/ontology · diff

git:20260907.ae194c2 to git:20260910.8c9b939

1 added, 1 removed. Audit A to A.

# Ontology Module - Agent Scaffolding
## Module Overview
**Purpose**: Active Inference Ontology processing, validation, and term mapping for GNN models
**Pipeline Step**: Step 10: Ontology processing (10_ontology.py)
**Category**: Semantic Validation / Ontology Management
**Status**: Production Ready
- **Version**: 3.2.0 (module `__version__` 1.7.0)
+ **Version**: re-exports canonical package `__version__` (SC-16)
**Last Updated**: 2026-09-04
---
## Core Functionality
### Primary Responsibilities
1. Extract ontology terms from GNN models
2. Validate against Active Inference Ontology
3. Map GNN components to ontological concepts
4. Generate ontology compliance reports
5. Identify semantic inconsistencies
### Key Capabilities
- Term extraction from GNN specifications
- Ontology compliance validation
- Semantic relationship mapping
- Hierarchical concept analysis
- Cross-reference validation
---
## API Reference
### Public Functions
#### `process_ontology(target_dir: Path, output_dir: Path, verbose: bool = False, **kwargs) -> bool`
**Description**: Main ontology processing function called by orchestrator (10_ontology.py). Processes GNN files for ontology validation and mapping.
**Parameters**:
- `target_dir` (Path): Directory containing GNN files to process
- `output_dir` (Path): Output directory for ontology results
- `verbose` (bool): Enable verbose logging (default: False)
- `strict_validation` (bool, optional): Require all terms to be in ontology (default: False; read from `**kwargs`)
- `recursive` (bool, optional): Process directories recursively (default: True; read from `**kwargs`)
- `ontology_terms_file` (Path, optional): Path to ontology terms JSON file (default: `src/gnn/ontology/act_inf_ontology_terms.json`; read from `**kwargs`)
- `**kwargs`: Additional processing options (other keys are accepted but not consumed)
**Returns**: `bool` - True if processing succeeded, False otherwise
```python
from gnn.ontology import process_ontology
from pathlib import Path
success = process_ontology(
target_dir=Path("input/gnn_files"),
output_dir=Path("output/10_ontology_output"),
ontology_terms_file=Path("src/gnn/ontology/act_inf_ontology_terms.json"),
strict_validation=True,
)
```
#### `parse_gnn_ontology_section(content: str) -> Dict[str, Any]`
**Description**: Extract the ontology annotation section (e.g. `## ActInfOntologyAnnotation`) from GNN Markdown content.
**Parameters**:
- `content` (str): Raw GNN Markdown content
**Returns**: `Dict[str, Any]` - Parsed ontology content (annotations + any extracted fields)
#### `load_defined_ontology_terms(ontology_terms_file: Path | None = None, *, search_paths: Sequence[Path] | None = None) -> Dict[str, Any]`
**Description**: Load the ontology term dictionary. Precedence: explicit `ontology_terms_file` (authoritative, fails closed) → caller-supplied `search_paths` (warn-and-continue on each miss) → built-in module-relative paths → built-in default term set. The `search_paths` keyword is the dependency-injection hook for tests and alternate installs.
**Returns**: `Dict[str, Any]` - Term definitions (including description and URI).
#### `build_ontology_terms(terms: List[str], *, descriptions: Dict[str, str] | None = None, uris: Dict[str, str] | None = None) -> Dict[str, Any]`
**Description**: Build a normalized ontology-terms dictionary in memory (the shape `load_defined_ontology_terms` returns and `validate_annotations` consumes), without writing a JSON file. Rejects empty names, exact duplicates, and case-folded duplicates (e.g. `["A", "a"]`) so the built vocabulary upholds the case-insensitive lookup invariant. Complement of `_normalise_ontology_terms`.
**Returns**: `Dict[str, Any]` - Term-name -> `{"description", "uri"?}` mapping.
#### `validate_annotations(annotations: List[str], ontology_terms: Dict[str, Any] | None = None) -> Dict[str, Any]`
**Description**: Validate ontology annotations (e.g. `A=LikelihoodMatrix`) against the known ontology term set.
**Parameters**:
- `annotations` (List[str]): Annotation strings
- `ontology_terms` (Dict[str, Any] | None): Optional explicit ontology term set (default: module’s loaded terms)
**Returns**: `Dict[str, Any]` - Validation details (valid/invalid annotations, suggestions when available)
#### `process_gnn_ontology(gnn_file: str, ontology_terms: Dict[str, Any] | None = None) -> Dict[str, Any]`
**Description**: Process ontology annotations for a single GNN file path (reads file, parses ontology section, validates annotations). Delegates the parse→load→validate pipeline to `analyze_ontology_content`.
#### `analyze_ontology_content(content: str, ontology_terms: Dict[str, Any] | None = None) -> Dict[str, Any]`
**Description**: Single pure entry point that parses GNN content and validates its annotations, returning `{"ontology_data", "validation_result", "ontology_terms"}`. Shared by `process_gnn_ontology` (file input) and `OntologyProcessor.process_ontology` (content input) so the pipeline exists in exactly one place.
#### `suggest_terms(annotations: List[str], ontology_terms: Dict[str, Any] | None = None, *, max_distance: int = 3) -> List[Dict[str, Any]]`
**Description**: Return nearest-ontology-term suggestions for unknown annotations. Each result is `{"annotation", "suggested_term", "description", "distance"}` ranked closest-first (distance `0` = substring match). Reuses the same case-folded substring + Levenshtein heuristic as `validate_annotations`, exposed for LLM/report consumers.
#### `summarise_coverage(validation_result: Dict[str, Any]) -> str`
**Description**: Render a `validate_annotations` result as a compact human-readable coverage line (e.g. `"3/4 annotations valid (coverage 75.0%); 1 suggestion"`). Pure helper for report/LLM consumers.
#### `parse_annotation(annotation: str) -> ParsedAnnotation`
**Description**: Parse a `KEY=VALUE` annotation into a `ParsedAnnotation` NamedTuple (`key`, `value`, `comment`), still a 3-tuple so positional unpacking keeps working. `key`/`comment` are `None` when absent.
#### `generate_ontology_report_for_file(gnn_file: Path, output_dir: Path, *, ontology_terms: Dict[str, Any] | None = None) -> Dict[str, Any]`
**Description**: Generate and write a per-file ontology report JSON for a single GNN file.
#### `validate_ontology_terms(terms: List[str] | str | None = None) -> bool`
**Description**: Convenience validator for terms/annotations (returns boolean validity; used by integrations/tests).
### Public Classes
#### `OntologyProcessor`
**Description**: Convenience wrapper exposing `process_ontology()` and `validate_terms()` around the functional API.
#### `OntologyValidator`
**Description**: Validator exposing `validate_ontology()` and `check_consistency()` for quick boolean checks.
#### `OntologyTermIndex`
**Description**: Prebuilt case-insensitive index over an ontology vocabulary for batch callers. Construct once via `OntologyTermIndex(terms)`, `.from_file(path)`, or `.from_names(...)`; then use `lookup(value)` (O(1) case-insensitive membership), `known_terms()`, `validate(annotations)`, `suggest(annotations)`, `len()`, and `in` checks. Immutable after construction; delegates to the module-level pure functions so behaviour stays in lock-step with the functional API.
---
## Ontology Structure
### Active Inference Ontology Terms
- **Core Concepts**: Belief, Preference, Action, Observation
- **Mathematical**: Matrix, Vector, Probability, Distribution
- **Process**: Inference, Learning, Planning, Control
- **Architecture**: Agent, Environment, Model, Policy
---
## Configuration
### Configuration Options
Consumed `**kwargs` on `process_ontology()`:
- `ontology_terms_file` (Path): Path to ontology terms JSON file (default: `src/gnn/ontology/act_inf_ontology_terms.json`)
- `strict_validation` (bool): Require all terms to be in ontology (default: `False`)
- `recursive` (bool): Process directories recursively (default: `True`)
No other configuration keys are read; term suggestions come from Levenshtein-distance matching in `processor.py`.
---
## Dependencies
### Required Dependencies
- `json` - Ontology file loading
- `pathlib` - File operations
### Internal Dependencies
- `utils.pipeline_template` - Logging utilities
- `pipeline.config` - Configuration management
- `ontology.processor` - Core processing logic
---
## Usage Examples
### Basic Usage
```python
from gnn.ontology import process_ontology
success = process_ontology(
target_dir=Path("input/gnn_files"),
output_dir=Path("output/10_ontology_output"),
ontology_terms_file=Path("src/gnn/ontology/act_inf_ontology_terms.json"),
)
```
### Single-file processing
```python
from gnn.ontology import process_gnn_ontology
result = process_gnn_ontology("input/gnn_files/discrete/simple_mdp.md")
print(result["success"], result.get("validation_result", {}))
```
---
## Output Specification
### Output Products
- `ontology_results.json` - Aggregate summary across processed files
- `*_ontology_report.json` - Per-model ontology validation reports
### Output Directory Structure
```
output/10_ontology_output/
├── ontology_results.json
├── actinf_pomdp_agent_ontology_report.json
├── deep_planning_horizon_ontology_report.json
└── ... (one per processed model)
```
---
## Validation Rules
### Compliance Checks
1. All GNN variables map to ontology terms
2. Connections align with ontological relationships
3. POMDP components match Active Inference structure
4. Terminology is consistent with ontology
### Warning Conditions
- Unrecognized terms (potential new concepts)
- Ambiguous mappings (multiple possible interpretations)
- Missing required ontological components
---
## Performance Characteristics
### Expected Performance
Lightweight JSON-based validation; runtime is dominated by file I/O.
---
## Error Handling
### Graceful Degradation
- **Ontology File Missing**: Use default ontology, log warning
- **Invalid Ontology Format**: Parse what's possible, log error
- **Invalid GNN Model**: Skip model, log error, continue with others
- **Term Validation Failure**: Log warning, continue processing
### Error Categories
1. **File I/O Errors**: Cannot read ontology file (recovery: use default ontology)
2. **Validation Errors**: Invalid ontology structure (recovery: skip validation)
3. **Term Extraction Errors**: Cannot extract terms from model (recovery: skip model)
4. **Mapping Errors**: Cannot generate term mappings (recovery: partial mapping)
### Error Recovery
- **Default Ontology**: Use built-in ontology if file unavailable
- **Partial Validation**: Validate what's possible, report failures
- **Resource Cleanup**: Proper cleanup of ontology resources on errors
---
## Integration Points
### Pipeline Integration
- **Input**: Receives parsed GNN models from Step 3 (gnn processing)
- **Output**: Generates ontology validation for Step 6 (validation), Step 11 (render), and Step 23 (report generation)
- **Dependencies**: Requires GNN parsing results from `3_gnn.py` output
### Module Dependencies
- **gnn/**: Reads parsed GNN model data for term extraction
- **validation/**: Provides ontology compliance for validation
- **render/**: Uses ontology mappings for code generation
- **report/**: Provides ontology compliance summaries
### External Integration
- **Ontology File**: JSON-based ontology term definitions
- **Active Inference Standards**: Validates against Active Inference ontology
### Data Flow
```
3_gnn.py (GNN parsing)
↓
10_ontology.py (Ontology processing)
↓
├→ 6_validation.py (Ontology compliance)
├→ 11_render.py (Term mapping)
├→ 23_report.py (Ontology reports)
└→ output/10_ontology_output/ (Ontology results)
```
---
## Testing
### Test Files
- `tests/ontology/test_ontology_overall.py` — module-level behaviour
- `tests/ontology/test_ontology_annotations.py` — annotation parsing/validation
- `tests/ontology/test_ontology_public_api.py` — public export surface
- `tests/ontology/test_ontology_composability.py` — composability helpers, vocabulary dedup invariant, MCP real-vocabulary behaviour
### Test Coverage
Measure on demand:
```bash
uv run --extra dev python -m pytest tests/ontology/ \
--cov=src/gnn/ontology --cov-report=term-missing
```
### Key Test Scenarios
1. Ontology term extraction
2. Ontology compliance validation
3. Semantic relationship mapping
4. Cross-reference validation
---
## MCP Integration
### Tools Registered
Registered by `src/gnn/ontology/mcp.py` `register_tools(mcp_instance)` (4 tools):
- `process_ontology` - Run ontology processing on a directory
- `validate_ontology_terms` - Validate a term or list of terms against the ontology
- `list_standard_ontology_terms` - List the standard ontology terms (derived from the real vocabulary via `load_defined_ontology_terms()`, so it cannot drift from what `validate_annotations` accepts)
### MCP File Location
- `src/gnn/ontology/mcp.py` - MCP tool registrations
---
## Troubleshooting
### Common Issues
#### Issue 1: Ontology validation fails
**Symptom**: Validation reports errors even for valid terms
**Cause**: Ontology terms file missing or outdated
**Solution**:
- Check that `src/gnn/ontology/act_inf_ontology_terms.json` exists
- Verify ontology terms file format is valid JSON
- Update ontology terms file if needed
- Use `--verbose` flag for detailed validation messages
#### Issue 2: Terms not found in ontology
**Symptom**: Valid Active Inference terms reported as invalid
**Cause**: Ontology terms file incomplete or term naming mismatch
**Solution**:
- Check term spelling and case sensitivity
- Verify ontology terms file includes all required terms
- Use `--strict-validation=False` for lenient validation
- Review ontology terms file structure
#### Issue 3: Semantic mapping incomplete
**Symptom**: Mapping generation produces incomplete results
**Cause**: Missing ontology relationships or incomplete GNN model
**Solution**:
- Ensure GNN model has complete ontology annotations
- Verify ontology terms file includes relationship data
- Check that GNN processing (step 3) completed successfully
---
## Version History
### Current Version: 3.2.0
**Features**:
- Ontology term extraction
- Ontology compliance validation
- Semantic relationship mapping
- Hierarchical concept analysis
- Cross-reference validation
**Known Issues**:
- None currently
### Roadmap
- **Next Version**: Enhanced semantic relationship detection
- **Future**: Automated ontology term suggestion
---
## References
### Related Documentation
- [Pipeline Overview](../../../README.md)
- [Architecture Guide](../../../ARCHITECTURE.md)
- [Active Inference Ontology](https://activeinference.org)
- [GNN Ontology Guide](../../../docs/gnn/advanced/gnn_ontology.md)
### External Resources
- [Active Inference Institute](https://activeinference.institute/)
- [Active Inference Ontology Documentation](../../../docs/gnn/advanced/ontology_system.md)
---
**Last Updated**: 2026-09-02
**Maintainer**: GNN Pipeline Team
**Status**: Production Ready
**Version**: 3.2.0
---
## Documentation
- **[README](README.md)**: Module Overview
- **[AGENTS](AGENTS.md)**: Agentic Workflows
- **[SPEC](SPEC.md)**: Architectural Specification
- **[SKILL](SKILL.md)**: Capability API