ontosql 0.1.0__tar.gz

ontosql-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ty_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.DS_Store
+*.egg

ontosql-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OntoSQL Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ontosql-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: ontosql
+Version: 0.1.0
+Summary: Semantic interoperability for SQLModel — JSON-LD and RDF export with ontology-aware fields (import ontosql)
+Project-URL: Homepage, https://github.com/eddiethedean/ontosql
+Project-URL: Documentation, https://github.com/eddiethedean/ontosql#readme
+Project-URL: Repository, https://github.com/eddiethedean/ontosql
+Project-URL: Issues, https://github.com/eddiethedean/ontosql/issues
+Project-URL: Changelog, https://github.com/eddiethedean/ontosql/blob/main/CHANGELOG.md
+Author: OntoSQL Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,json-ld,ontology,rdf,semantic-web,sqlmodel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: rdflib>=7.0.0
+Requires-Dist: sqlmodel>=0.0.14
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: orjson>=3.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ty>=0.0.37; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: orjson>=3.9; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# OntoSQL
+
+**Semantic interoperability for SQLModel** — enrich operational models with ontology metadata and export JSON-LD and RDF without leaving Python.
+
+```bash
+pip install ontosql
+pip install "ontosql[fastapi]"   # optional API helpers
+```
+
+## Quick start
+
+```python
+from sqlmodel import Field, SQLModel
+from ontosql import OntoMixin, onto_field, onto_model
+
+
+@onto_model(type_="schema:Person", iri_template="http://example.org/person/{id}")
+class Person(SQLModel, OntoMixin, table=False):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = onto_field(ontology="schema:name")
+
+
+person = Person(id=1, name="Ada Lovelace")
+print(person.to_jsonld())
+print(person.to_rdf(format="turtle"))
+```
+
+## Features (0.1.0)
+
+- `onto_field()` — attach ontology CURIEs/IRIs to model fields
+- `onto_model()` — declare RDF type and instance IRI templates on classes
+- `PrefixRegistry` — manage namespace prefixes for JSON-LD `@context`
+- `to_jsonld()` / `to_rdf()` — export instances to semantic web formats
+- FastAPI response helpers with content negotiation (`ontosql[fastapi]`)
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from ontosql.fastapi import negotiate_onto_response
+
+app = FastAPI()
+
+@app.get("/person/{person_id}")
+def get_person(person_id: int, request: Request):
+    person = Person(id=person_id, name="Ada Lovelace")
+    return negotiate_onto_response(request, person)
+```
+
+See [examples/fastapi_demo.py](https://github.com/eddiethedean/ontosql/blob/main/examples/fastapi_demo.py).
+
+## Limitations (0.1.0)
+
+- No RDF import or SHACL generation yet (planned for 0.2+)
+- Foreign-key-only relationships export as `@id` references, not nested objects (use a nested `OntoMixin` field for embedded objects)
+- JSON-LD framing requires a future `ontosql[jsonld]` extra (PyLD)
+- Do not map two fields to the same ontology property; if you do, nested objects are preferred over FK integers (a warning is emitted)
+
+## Documentation
+
+- [Roadmap](https://github.com/eddiethedean/ontosql/blob/main/docs/ROADMAP.md)
+- [Technical specification](https://github.com/eddiethedean/ontosql/blob/main/docs/SPECS.md)
+- [Project plan](https://github.com/eddiethedean/ontosql/blob/main/docs/PLAN.md)
+- [Dependency assessment](https://github.com/eddiethedean/ontosql/blob/main/docs/DEPS.md)
+- [Changelog](https://github.com/eddiethedean/ontosql/blob/main/CHANGELOG.md)
+
+## Development
+
+See [Releasing](https://github.com/eddiethedean/ontosql/blob/main/docs/RELEASING.md) for the version publish checklist.
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests
+ruff format src tests
+ty check
+pytest --cov=ontosql --cov-fail-under=100
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/eddiethedean/ontosql/blob/main/LICENSE).

ontosql-0.1.0/README.md

@@ -0,0 +1,81 @@
+# OntoSQL
+
+**Semantic interoperability for SQLModel** — enrich operational models with ontology metadata and export JSON-LD and RDF without leaving Python.
+
+```bash
+pip install ontosql
+pip install "ontosql[fastapi]"   # optional API helpers
+```
+
+## Quick start
+
+```python
+from sqlmodel import Field, SQLModel
+from ontosql import OntoMixin, onto_field, onto_model
+
+
+@onto_model(type_="schema:Person", iri_template="http://example.org/person/{id}")
+class Person(SQLModel, OntoMixin, table=False):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = onto_field(ontology="schema:name")
+
+
+person = Person(id=1, name="Ada Lovelace")
+print(person.to_jsonld())
+print(person.to_rdf(format="turtle"))
+```
+
+## Features (0.1.0)
+
+- `onto_field()` — attach ontology CURIEs/IRIs to model fields
+- `onto_model()` — declare RDF type and instance IRI templates on classes
+- `PrefixRegistry` — manage namespace prefixes for JSON-LD `@context`
+- `to_jsonld()` / `to_rdf()` — export instances to semantic web formats
+- FastAPI response helpers with content negotiation (`ontosql[fastapi]`)
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from ontosql.fastapi import negotiate_onto_response
+
+app = FastAPI()
+
+@app.get("/person/{person_id}")
+def get_person(person_id: int, request: Request):
+    person = Person(id=person_id, name="Ada Lovelace")
+    return negotiate_onto_response(request, person)
+```
+
+See [examples/fastapi_demo.py](https://github.com/eddiethedean/ontosql/blob/main/examples/fastapi_demo.py).
+
+## Limitations (0.1.0)
+
+- No RDF import or SHACL generation yet (planned for 0.2+)
+- Foreign-key-only relationships export as `@id` references, not nested objects (use a nested `OntoMixin` field for embedded objects)
+- JSON-LD framing requires a future `ontosql[jsonld]` extra (PyLD)
+- Do not map two fields to the same ontology property; if you do, nested objects are preferred over FK integers (a warning is emitted)
+
+## Documentation
+
+- [Roadmap](https://github.com/eddiethedean/ontosql/blob/main/docs/ROADMAP.md)
+- [Technical specification](https://github.com/eddiethedean/ontosql/blob/main/docs/SPECS.md)
+- [Project plan](https://github.com/eddiethedean/ontosql/blob/main/docs/PLAN.md)
+- [Dependency assessment](https://github.com/eddiethedean/ontosql/blob/main/docs/DEPS.md)
+- [Changelog](https://github.com/eddiethedean/ontosql/blob/main/CHANGELOG.md)
+
+## Development
+
+See [Releasing](https://github.com/eddiethedean/ontosql/blob/main/docs/RELEASING.md) for the version publish checklist.
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests
+ruff format src tests
+ty check
+pytest --cov=ontosql --cov-fail-under=100
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/eddiethedean/ontosql/blob/main/LICENSE).

ontosql-0.1.0/docs/DEPS.md

@@ -0,0 +1,196 @@
+# OntoSQL Dependency Ecosystem Assessment
+
+## Overview
+
+This document evaluates recommended Python package dependencies and ecosystem integrations for **ontosql**. The goal is to maintain a lightweight, Pythonic, operationally focused semantic interoperability framework centered on SQLModel and FastAPI.
+
+## Dependency Philosophy
+
+The `ontosql` package should maintain:
+
+- A small and stable core
+- Optional extras for advanced integrations
+- Strong SQLModel compatibility
+- Minimal developer friction
+- Pythonic APIs over RDF-native complexity
+
+The package should avoid becoming a heavyweight semantic-web framework.
+
+## Core Dependencies
+
+### SQLModel
+
+- Primary operational model layer
+- SQLAlchemy + Pydantic integration
+- FastAPI-native ergonomics
+
+### Pydantic
+
+- Validation and serialization
+- Type system foundation
+- JSON schema generation
+
+### typing-extensions
+
+- Advanced typing compatibility
+
+### RDFLib
+
+- RDF graph backend
+- Serialization and parsing
+- Namespace handling
+
+## FastAPI Ecosystem Extras
+
+### FastAPI
+
+- Ontology-aware API integration
+- Content negotiation
+- OpenAPI enhancement
+
+### orjson
+
+- High-performance JSON serialization
+- Efficient JSON-LD support
+
+## Semantic Validation Extras
+
+### pySHACL
+
+- SHACL validation support
+- RDF graph validation
+- Enterprise interoperability validation
+
+## JSON-LD Ecosystem
+
+### PyLD
+
+- JSON-LD compaction
+- Framing
+- Expansion
+- Canonicalization
+
+PyLD significantly improves JSON-LD capabilities beyond basic RDFLib support.
+
+## Graph Database Integrations
+
+### SPARQLWrapper
+
+- SPARQL endpoint communication
+- RDF graph database interoperability
+
+### Neo4j Python Driver
+
+- Property graph integrations
+- Hybrid knowledge graph architectures
+
+## AI and LLM Ecosystem
+
+### Instructor
+
+- Structured LLM extraction into Pydantic models
+- Strong alignment with OntoSQL architecture
+
+### PydanticAI
+
+- Typed AI agent systems
+- Structured ontology extraction
+
+### DeepOnto
+
+- Ontology alignment
+- Semantic embeddings
+- AI-assisted ontology workflows
+
+## Developer Tooling
+
+### pytest
+
+- Testing framework
+
+### ty
+
+- Static typing validation
+
+### ruff
+
+- Linting and formatting
+
+### mkdocs-material
+
+- Documentation platform
+- Developer experience optimization
+
+## Future Integrations
+
+### Owlready2
+
+- OWL reasoning support
+- Ontology manipulation
+
+### networkx
+
+- Graph algorithms
+- Graph traversal
+
+### Polars
+
+- DataFrame interoperability
+- Typed ETL pipelines
+- Ontology-aware DataFrame workflows
+
+## Extras in pyproject.toml (0.1.0)
+
+```toml
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100", "orjson>=3.9"]
+dev = ["pytest", "pytest-cov", "ty", "ruff", "httpx", "fastapi", "orjson", ...]
+```
+
+- **`fastapi`** — installs FastAPI and orjson; `ontosql.fastapi` uses orjson for JSON-LD responses when available
+- **`dev`** — test, lint, and type-check tooling
+
+Install examples:
+
+```bash
+pip install ontosql
+pip install ontosql[fastapi]
+pip install -e ".[dev]"
+```
+
+## Proposed future extras
+
+The following are **not** yet defined in `pyproject.toml` but are under consideration:
+
+```toml
+jsonld = ["PyLD"]           # framing and advanced JSON-LD
+shacl = ["pySHACL"]         # SHACL validation
+graphdb = ["SPARQLWrapper", "neo4j"]
+ai = ["instructor", "pydantic-ai", "deeponto"]
+owl = ["Owlready2"]
+polars = ["polars"]
+```
+
+## Strategic Recommendations
+
+**Strongest foundational dependencies:**
+
+- SQLModel
+- Pydantic
+- RDFLib
+
+**Highest-value optional integrations:**
+
+- FastAPI
+- PyLD
+- pySHACL
+- Instructor
+
+**Highest long-term strategic opportunities:**
+
+- PydanticAI
+- Polars
+- Neo4j
+- DeepOnto
+
+OntoSQL should expose Pythonic model-centric APIs rather than RDF-native APIs. RDFLib should remain an internal implementation detail wherever possible.

ontosql-0.1.0/docs/PLAN.md

@@ -0,0 +1,103 @@
+# OntoSQL Project Plan
+
+## Vision
+
+Build **ontosql** — a Python package that combines SQLModel, Pydantic, FastAPI, and ontology tooling into a unified semantic application framework. Developers define operational database models once and automatically gain semantic interoperability through JSON-LD, RDF, SHACL, and ontology-aware APIs.
+
+```bash
+pip install ontosql
+```
+
+## Core Thesis
+
+Traditional ontology tooling is operationally difficult, while FastAPI + SQLModel ecosystems are highly ergonomic. OntoSQL bridges those worlds by adding ontology metadata and graph interoperability to normal Python web applications.
+
+## Primary Goals
+
+- Preserve SQLModel ergonomics
+- Add ontology metadata to fields and models
+- Enable JSON-LD and RDF export/import
+- Generate SHACL shapes automatically
+- Integrate deeply with FastAPI
+- Support graph database synchronization
+- Remain Pythonic and developer-friendly
+
+## Target Users
+
+- Enterprise data platform teams
+- Knowledge graph engineers
+- AI/RAG platform developers
+- FastAPI backend teams
+- Government and defense metadata systems
+- Research and biomedical platforms
+
+## MVP Scope
+
+Version 0.1 should focus on:
+
+- `OntoMixin`
+- `onto_field()`
+- JSON-LD export
+- RDFLib graph export
+- `PrefixRegistry`
+- FastAPI content negotiation
+
+## Non-Goals for v1
+
+- Full OWL reasoning engine
+- Native graph database query language
+- Complex ontology editing UI
+- Replacing RDF-native tooling like Protégé
+
+## Suggested Stack
+
+| Layer | Packages |
+|-------|----------|
+| Models | SQLModel, Pydantic v2 |
+| API | FastAPI |
+| Graph | RDFLib |
+| Validation | pySHACL |
+| HTTP | httpx |
+| Typing | typing_extensions |
+
+## Roadmap
+
+### v0.1 (released)
+
+- Ontology field metadata (`onto_field`, `@onto_model`)
+- JSON-LD serialization (including typed literals and duplicate-property handling)
+- RDF export (Turtle, JSON-LD, N-Triples, RDF/XML)
+- `PrefixRegistry`
+- FastAPI content negotiation and response classes (`ontosql[fastapi]`)
+
+### v0.2
+
+- SHACL generation
+- RDF import
+- Extended prefix / vocabulary management
+
+### v0.3
+
+- FastAPI `OntoRouter` and OpenAPI semantic enrichment
+
+### v0.4
+
+- Graph synchronization adapters
+- SPARQL endpoint publishing
+
+### v1.0
+
+- Stable public API for `ontosql`
+- Production examples
+- Schema packs
+- Full documentation
+
+## Long-Term Vision
+
+OntoSQL becomes the operational semantic layer for Python applications:
+
+- Typed knowledge graphs
+- AI semantic memory systems
+- Metadata governance
+- Enterprise interoperability
+- LLM extraction pipelines

ontosql-0.1.0/docs/RELEASING.md

@@ -0,0 +1,48 @@
+# Releasing OntoSQL
+
+Checklist for publishing a new version.
+
+## Pre-release
+
+1. Ensure `version` in `pyproject.toml` matches the release tag.
+2. Update `CHANGELOG.md` (move items from `[Unreleased]` to a new version section).
+3. Run the full CI suite locally:
+
+   ```bash
+   pip install -e ".[dev]"
+   ruff check src tests
+   ruff format --check src tests
+   ty check
+   pytest --cov=ontosql --cov-fail-under=100
+   ```
+
+4. Build and smoke-test the wheel:
+
+   ```bash
+   pip install build
+   python -m build
+   pip install dist/ontosql-*.whl
+   python -c "import ontosql; print(ontosql.__version__)"
+   ```
+
+## GitHub release
+
+```bash
+git tag -a v0.1.0 -m "Release 0.1.0"
+git push origin v0.1.0
+```
+
+Create a GitHub release from the tag and paste the relevant `CHANGELOG.md` section.
+
+## PyPI
+
+The PyPI distribution name is **`ontosql`**.
+
+```bash
+python -m build
+pip install twine
+twine check dist/*
+twine upload dist/*
+```
+
+Requires PyPI credentials configured (`~/.pypirc` or `TWINE_USERNAME` / `TWINE_PASSWORD`).