Metadata-Version: 2.4
Name: ontocast
Version: 0.6.0
Summary: Agentic ontology and knowledge graph co-generation
Project-URL: Changelog, https://github.com/growgraph/ontocast/blob/main/CHANGELOG.md
Project-URL: Documentation, https://growgraph.github.io/ontocast
Project-URL: Homepage, https://github.com/growgraph/ontocast
Project-URL: Issues, https://github.com/growgraph/ontocast/issues
Project-URL: Repository, https://github.com/growgraph/ontocast
Author-email: Alexander Belikov <alexander@growgraph.dev>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,knowledge-graph,llm,ontology,rdf,semantic-web,sparql,triple-extraction
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: <4.0,>=3.12
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: langchain-core<2,>=1.0
Requires-Dist: langgraph<2,>=1.0
Requires-Dist: numpy<3,>=1.26
Requires-Dist: oxrdflib<0.6,>=0.5.0
Requires-Dist: pydantic-settings<3,>=2.5.0
Requires-Dist: pydantic<3,>=2.11.9
Requires-Dist: pyld<4,>=3.0
Requires-Dist: pyoxigraph<0.6,>=0.5.8
Requires-Dist: pyyaml<7,>=6.0.2
Requires-Dist: rdflib<8,>=7.1.4
Requires-Dist: scikit-learn<2,>=1.4
Provides-Extra: all
Requires-Dist: click<9,>=8.1.8; extra == 'all'
Requires-Dist: docling-core[chunking]<3,>=2.57.0; extra == 'all'
Requires-Dist: docling>=2.57.0; extra == 'all'
Requires-Dist: duckduckgo-search>=8.1.1; extra == 'all'
Requires-Dist: easyocr>=1.7.2; extra == 'all'
Requires-Dist: fastapi<1,>=0.115.0; extra == 'all'
Requires-Dist: fastembed<1,>=0.8.0; extra == 'all'
Requires-Dist: hdbscan>=0.8.41; extra == 'all'
Requires-Dist: lancedb>=0.33.0; extra == 'all'
Requires-Dist: langchain-anthropic<2,>=1.0; extra == 'all'
Requires-Dist: langchain-google-genai<5,>=4.0; extra == 'all'
Requires-Dist: langchain-ollama<2,>=1.0; extra == 'all'
Requires-Dist: langchain-openai<2,>=1.0; extra == 'all'
Requires-Dist: networkx<4,>=3.0; extra == 'all'
Requires-Dist: pyshacl>=0.30.0; extra == 'all'
Requires-Dist: python-dotenv<2,>=1.0.0; extra == 'all'
Requires-Dist: python-multipart<1,>=0.0.22; extra == 'all'
Requires-Dist: qdrant-client<2,>=1.15.1; extra == 'all'
Requires-Dist: rich<16,>=14.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=5.1.1; extra == 'all'
Requires-Dist: starlette<2,>=1.0; extra == 'all'
Requires-Dist: suthing<1,>=0.4.1; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Requires-Dist: umap-learn>=0.5.12; extra == 'all'
Requires-Dist: uvicorn[standard]<1,>=0.32.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic<2,>=1.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anyio>=4.4.0; extra == 'dev'
Requires-Dist: pre-commit>=4.2.0; extra == 'dev'
Requires-Dist: pytest-dotenv>=0.5.2; extra == 'dev'
Requires-Dist: pytest-order>=1.3.0; extra == 'dev'
Requires-Dist: pytest>=8.3.5; extra == 'dev'
Requires-Dist: ruff>=0.11.2; extra == 'dev'
Requires-Dist: ty>=0.0.14; extra == 'dev'
Provides-Extra: doc-processing
Requires-Dist: docling-core[chunking]<3,>=2.57.0; extra == 'doc-processing'
Requires-Dist: docling>=2.57.0; extra == 'doc-processing'
Requires-Dist: easyocr>=1.7.2; extra == 'doc-processing'
Requires-Dist: sentence-transformers>=5.1.1; extra == 'doc-processing'
Provides-Extra: docs
Requires-Dist: griffe<2.0.0; extra == 'docs'
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == 'docs'
Requires-Dist: mkdocs-glightbox>=0.4.0; extra == 'docs'
Requires-Dist: mkdocs-jupyter>=0.25.1; extra == 'docs'
Requires-Dist: mkdocs-literate-nav>=0.6.2; extra == 'docs'
Requires-Dist: mkdocs-material>=9.6.14; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings-python>=2.0.3; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.29.1; extra == 'docs'
Provides-Extra: documents
Requires-Dist: docling-core[chunking]<3,>=2.57.0; extra == 'documents'
Provides-Extra: google
Requires-Dist: langchain-google-genai<5,>=4.0; extra == 'google'
Provides-Extra: graph
Requires-Dist: networkx<4,>=3.0; extra == 'graph'
Provides-Extra: lancedb
Requires-Dist: fastembed<1,>=0.8.0; extra == 'lancedb'
Requires-Dist: lancedb>=0.33.0; extra == 'lancedb'
Provides-Extra: ollama
Requires-Dist: langchain-ollama<2,>=1.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: langchain-openai<2,>=1.0; extra == 'openai'
Provides-Extra: plot
Requires-Dist: pygraphviz>=1.14; extra == 'plot'
Provides-Extra: qdrant
Requires-Dist: fastembed<1,>=0.8.0; extra == 'qdrant'
Requires-Dist: qdrant-client<2,>=1.15.1; extra == 'qdrant'
Provides-Extra: semantic-chunking
Requires-Dist: hdbscan>=0.8.41; extra == 'semantic-chunking'
Requires-Dist: sentence-transformers>=5.1.1; extra == 'semantic-chunking'
Requires-Dist: torch>=2.0; extra == 'semantic-chunking'
Requires-Dist: umap-learn>=0.5.12; extra == 'semantic-chunking'
Provides-Extra: server
Requires-Dist: click<9,>=8.1.8; extra == 'server'
Requires-Dist: docling-core[chunking]<3,>=2.57.0; extra == 'server'
Requires-Dist: fastapi<1,>=0.115.0; extra == 'server'
Requires-Dist: python-dotenv<2,>=1.0.0; extra == 'server'
Requires-Dist: python-multipart<1,>=0.0.22; extra == 'server'
Requires-Dist: rich<16,>=14.0.0; extra == 'server'
Requires-Dist: starlette<2,>=1.0; extra == 'server'
Requires-Dist: suthing<1,>=0.4.1; extra == 'server'
Requires-Dist: uvicorn[standard]<1,>=0.32.0; extra == 'server'
Provides-Extra: shacl
Requires-Dist: pyshacl>=0.30.0; extra == 'shacl'
Provides-Extra: sparse
Requires-Dist: fastembed<1,>=0.8.0; extra == 'sparse'
Provides-Extra: web-search
Requires-Dist: duckduckgo-search>=8.1.1; extra == 'web-search'
Description-Content-Type: text/markdown

# OntoCast <img src="https://raw.githubusercontent.com/growgraph/ontocast/refs/heads/main/docs/assets/favicon.ico" alt="OntoCast logo" style="height: 32px; width:32px;"/>

**Agentic ontology-assisted extraction of RDF knowledge graphs from documents.**

![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)
[![PyPI version](https://badge.fury.io/py/ontocast.svg)](https://badge.fury.io/py/ontocast)
[![PyPI Downloads](https://static.pepy.tech/badge/ontocast)](https://pepy.tech/projects/ontocast)
[![Docs](https://img.shields.io/badge/docs-growgraph.github.io-orange.svg)](https://growgraph.github.io/ontocast/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![pre-commit](https://github.com/growgraph/ontocast/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/growgraph/ontocast/actions/workflows/pre-commit.yml)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17796467.svg)](https://doi.org/10.5281/zenodo.17796467)

OntoCast turns unstructured text into queryable RDF: it **co-evolves** domain ontologies and fact graphs in a parallel map/reduce pipeline, with RDF 1.2 provenance, entity disambiguation across chunks, and optional vector-backed ontology retrieval. Run it as a REST service, a batch CLI, or embed the pipeline in your own LangChain / LangGraph agent.

**Documentation:** [growgraph.github.io/ontocast](https://growgraph.github.io/ontocast/)

---

## Why OntoCast

Most extractors dump triples and leave ontology drift to you. OntoCast treats schema and instance data as one loop: per-chunk render → critic → merge, with GraphUpdate patches (insert/delete) instead of regenerating whole graphs, SHACL validation with LLM-free autofix, and a light install so you can embed the core without pulling Docling, gRPC, or ONNX.

---

## Features

- **Parallel ontology + facts loops** — concurrent per-unit render/critic with configurable workers
- **GraphUpdate patches** — token-efficient insert/delete ops, not full-graph regeneration
- **Entity disambiguation** — embedding + symbolic alignment across chunks
- **RDF 1.2 provenance** — quoted triples / provenance artifacts; optional `strip_provenance`
- **Ontology context** — catalog selection, vector retrieval (LanceDB or Qdrant), or a fixed ontology
- **Facts validation** — invariants, SHACL, and machine repairs without an extra LLM pass
- **Stores** — in-memory pyoxigraph by default; Fuseki for persistence; tenancy by tenant/project
- **LLM caching** — disk cache, in-flight limits, optional read-only / batch pre-warm
- **Embeddable** — `ontocast_tools`, `run_unit_pipeline`, or a LangGraph node

---

## Install

Pick at least one LLM provider extra. Add `server` for the CLI and HTTP API:

```sh
uv add "ontocast[server,openai]"
# or: pip install "ontocast[server,openai]"
```

Common add-ons: `doc-processing` (PDF/DOCX), `lancedb` or `qdrant` (ontology retrieval), `shacl` (shape validation).

```sh
uv add "ontocast[server,openai,doc-processing,lancedb,shacl]"
```

Full extras table: [Installation](https://growgraph.github.io/ontocast/getting_started/installation/).

---

## Quick start

```bash
cp .env.example .env
# Set LLM_API_KEY (and LLM_PROVIDER / LLM_MODEL_NAME as needed)

ontocast serve
curl -X POST http://localhost:8999/process -F "file=@document.pdf"
```

Batch without a server:

```bash
ontocast process --input-path ./document.pdf --head-chunks 5 --output-dir ./out
```

Omit `FUSEKI_URI` for in-memory pyoxigraph. Details: [Quick Start](https://growgraph.github.io/ontocast/getting_started/quickstart/).

### Supplying Your Ontologies

OntoCast uses seed ontologies (in Turtle `.ttl` format) to guide extraction. Provide yours in two ways:

1. **Directory Seed:** Set `ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/your/ontologies` in your `.env`. All `.ttl` files in that folder sync automatically on startup.
2. **API Upload:** Register schemas dynamically with the running server:
   ```bash
   curl -X POST "http://localhost:8999/ontologies?tenant=ontocast&project=test" -F "file=@my_ontology.ttl"
   ```

---

## Embed in your agent

```python
from langchain.agents import create_agent
from ontocast import Config, ToolBox, ontocast_tools

tools = await ToolBox.acreate(Config.in_memory())
await tools.initialize()

agent = create_agent(
    model,
    tools=[*ontocast_tools(tools)],
    prompt="Edit the ontology from the user's text.",
)
```

Also: `run_unit_pipeline` for a single passage, or `make_ontocast_node` inside your own LangGraph — see [Embedding OntoCast](https://growgraph.github.io/ontocast/user_guide/embedding/).

---

## Workflow

![Workflow diagram](docs/assets/graph.png)

1. Convert → chunk prepare (segment, tag, filter, size)
2. Parallel ontology render → normalize → consolidate → structural check → critic
3. Parallel facts render → merge / disambiguate → validate (invariants, SHACL, autofix)
4. Serialize to the triple store; return Turtle from the API

[Workflow guide](https://growgraph.github.io/ontocast/user_guide/workflow/) · landscape: [`graph.lr.png`](docs/assets/graph.lr.png) · per-unit: [`ontology_loop`](docs/assets/ontology_loop.png), [`facts_loop`](docs/assets/facts_loop.png)

---

## Documentation

Everything lives at **[growgraph.github.io/ontocast](https://growgraph.github.io/ontocast/)**:

| | |
|---|---|
| [Installation](https://growgraph.github.io/ontocast/getting_started/installation/) · [Quick Start](https://growgraph.github.io/ontocast/getting_started/quickstart/) | Getting started |
| [Core Concepts](https://growgraph.github.io/ontocast/user_guide/concepts/) · [Workflow](https://growgraph.github.io/ontocast/user_guide/workflow/) · [Configuration](https://growgraph.github.io/ontocast/user_guide/configuration/) | How it works |
| [API](https://growgraph.github.io/ontocast/user_guide/api/) · [Embedding](https://growgraph.github.io/ontocast/user_guide/embedding/) · [Tenancy](https://growgraph.github.io/ontocast/user_guide/tenancy/) | Integrate |
| [Ontology Context](https://growgraph.github.io/ontocast/user_guide/ontology_context/) · [Validation / SHACL](https://growgraph.github.io/ontocast/user_guide/validation/) · [Triple Stores](https://growgraph.github.io/ontocast/user_guide/triple_stores/) | Operate |
| [API Reference](https://growgraph.github.io/ontocast/reference/) | Python API |

Release notes: [CHANGELOG.md](CHANGELOG.md)

---

## Contributing

See [Contributing](https://growgraph.github.io/ontocast/contributing/). Issues and discussion: [GitHub](https://github.com/growgraph/ontocast).

## License

Apache License 2.0 — see [LICENSE](LICENSE).
