Metadata-Version: 2.4
Name: openontologylite
Version: 0.1.0a2
Summary: A lightweight, vendor-neutral semantic layer for portable organizational knowledge.
Project-URL: Homepage, https://github.com/sekacorn/OpenOntologyLite
Project-URL: Repository, https://github.com/sekacorn/OpenOntologyLite
Project-URL: Issues, https://github.com/sekacorn/OpenOntologyLite/issues
Project-URL: Documentation, https://github.com/sekacorn/OpenOntologyLite/tree/main/docs
Author: sekacorn
License: MIT
License-File: LICENSE
Keywords: ai,metadata,ontology,semantic-layer,validation
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pyyaml<7,>=6.0.1
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: bandit>=1.7.9; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Description-Content-Type: text/markdown

# OpenOntologyLite

OpenOntologyLite makes organizational meaning portable across AI models, agent frameworks, databases, and vendors.

## Status

Ready for public alpha release preparation with documented limitations.

## Alpha Warning

OpenOntologyLite is `0.1.0a2` alpha software. The format may evolve before stable 1.0, and diff classifications are conservative rule-based guidance rather than legal, operational, or authorization guarantees.

## Why It Exists

Organizations increasingly describe their work inside AI systems, agent frameworks, RAG stores, policy engines, and vendor platforms. OpenOntologyLite asks a practical question: can an organization move operational knowledge between systems without rebuilding the meaning of its business?

## Core Capabilities

- YAML and JSON ontology loading with safe parsers.
- Typed entities, properties, relationships, actions, permissions, and preconditions.
- Structural and semantic validation with stable machine-readable codes.
- Deterministic canonical JSON and SHA-256 digest generation.
- Cycle analysis for relationships and reference properties.
- JSON Schema 2020-12, Mermaid, Markdown documentation, inspection, and diff exports.
- Local-first operation with no telemetry, network calls, database, server, cloud account, or AI model requirement.

## Installation

```powershell
python -m pip install openontologylite
```

For development:

```powershell
python -m pip install -e ".[dev]"
```

## Quick Start

```powershell
openontology validate examples/customer_support.yaml
openontology inspect examples/customer_support.yaml
openontology digest examples/customer_support.yaml
openontology export-json-schema examples/customer_support.yaml --output build/customer-support.schema.json
openontology export-mermaid examples/customer_support.yaml --output build/customer-support.mmd
openontology docs examples/customer_support.yaml --output build/customer-support.md
```

## Example Ontology

```yaml
schema_version: "1.0"
ontology:
  id: customer-service
  name: Customer Service Ontology
  version: "1.0.0"
  namespace: example.customer_service
entities:
  Customer:
    properties:
      customer_id:
        type: string
        required: true
      account_status:
        type: string
        required: true
        enum: [active, suspended, closed]
```

## Python API

```python
from open_ontology_lite import load_ontology, validate_ontology, ontology_digest

ontology = load_ontology("examples/customer_support.yaml")
report = validate_ontology(ontology)
print(report.ok)
print(ontology_digest(ontology))
```

## Validation Example

Validation returns stable codes, messages, logical paths, suggestions, and context. Strict permission validation is the default; undeclared permissions fail unless non-strict mode is requested.

```powershell
openontology validate tests/fixtures/invalid/undeclared_permission.yaml --json
```

## Diff Example

```powershell
openontology diff tests/fixtures/diff/customer-support-v1.yaml tests/fixtures/diff/customer-support-v2.yaml
```

Diff exit behavior:

- `0`: no breaking changes detected;
- `1`: breaking changes detected;
- `2`: invalid input or execution error.

## JSON Schema Export

OpenOntologyLite exports deterministic JSON Schema 2020-12 documents. Some ontology semantics, such as actions, permissions, and relationship intent, are lossy in JSON Schema and are documented rather than represented as perfect round-trip data.

## Mermaid Export

The Mermaid command emits source text only. It does not require Mermaid to be installed.

## Ecosystem Position

OpenOntologyLite is designed to stand alone in the `0.1.0` alpha line while remaining friendly to later integrations with Forge, PrivateAIStack, ModelSwapBench, AgentPolicyPack, AIAuditLog, and OpenAIMeter.

## Security Model

Ontology files are untrusted input. The package uses safe YAML loading, file-size, parsed-node, and nesting limits, non-executing preconditions, deterministic serialization, and escaping for Markdown and Mermaid outputs. CLI export commands validate ontologies before generating derived artifacts. OpenOntologyLite does not resolve remote schema references or execute expressions.

## Limitations

- No full RDF or OWL compatibility.
- No SPARQL.
- No general-purpose inference engine.
- No database synchronization.
- No graphical editor.
- No action execution.
- No authorization enforcement.
- Preconditions are declarative text only.
- No remote schema resolution.
- No hosted service.
- Diff classification is rule-based and conservative.
- JSON Schema export may be lossy for ontology-specific semantics.
- Relationship cycles are reported but not automatically invalid.
- Format may evolve before stable 1.0.

## Roadmap

Current alpha, `0.1.0a2`:

- Added aliases for entities, properties, relationships, and actions.
- Added alias validation with stable validation codes.
- Added rename-aware diffing for alias-backed entity, relationship, and action renames.
- Added migration suggestions in diff output.
- Hardened CLI exports so invalid ontologies are rejected before JSON Schema, Mermaid, or Markdown generation.
- Improved loader resilience with iterative depth checking, parsed-node limits, and safer file error handling.
- Improved JSON Schema export for nullable references and deterministic Decimal serialization.

Next alpha, `0.1.0a3`:

- Additional exporters.
- Stronger resource-limit configuration.
- More detailed migration hints.
- Forge adapter.
- ModelSwapBench fixtures.
- PrivateAIStack RAG metadata.
- Policy hooks for AgentPolicyPack.

Later, `0.2`:

- Optional SQLite catalog.
- Ontology package imports.
- Modular namespaces.
- Signed manifests.
- Provenance metadata.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Run Ruff, mypy strict, pytest with branch coverage, Bandit, pip-audit, build, and Twine check before release preparation.

## License

MIT.

## Author

sekacorn
