{"id":39404999,"url":"https://github.com/growgraph/ontocast","last_synced_at":"2026-01-18T03:28:52.701Z","repository":{"id":298664061,"uuid":"958212587","full_name":"growgraph/ontocast","owner":"growgraph","description":"Agentic Ontology Assisted Framework for Semantic Triple Extraction","archived":false,"fork":false,"pushed_at":"2026-01-16T17:27:48.000Z","size":20435,"stargazers_count":95,"open_issues_count":7,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-17T04:54:18.139Z","etag":null,"topics":["agentic-framework","knowledge-graph","ontology","rdf","semantic"],"latest_commit_sha":null,"homepage":"https://growgraph.github.io/ontocast/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/growgraph.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-31T20:36:17.000Z","updated_at":"2026-01-15T20:49:55.000Z","dependencies_parsed_at":"2025-09-19T20:17:47.697Z","dependency_job_id":"98f3c007-363d-4e61-834d-b6d56123eb19","html_url":"https://github.com/growgraph/ontocast","commit_stats":null,"previous_names":["growgraph/ontocast"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/growgraph/ontocast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growgraph%2Fontocast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growgraph%2Fontocast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growgraph%2Fontocast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growgraph%2Fontocast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/growgraph","download_url":"https://codeload.github.com/growgraph/ontocast/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/growgraph%2Fontocast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28528058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-framework","knowledge-graph","ontology","rdf","semantic"],"created_at":"2026-01-18T03:28:52.594Z","updated_at":"2026-01-18T03:28:52.665Z","avatar_url":"https://github.com/growgraph.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OntoCast \u003cimg src=\"https://raw.githubusercontent.com/growgraph/ontocast/refs/heads/main/docs/assets/favicon.ico\" alt=\"Agentic Ontology Triplecast logo\" style=\"height: 32px; width:32px;\"/\u003e\n\n### Agentic ontology-assisted framework for semantic triple extraction\n\n![Python](https://img.shields.io/badge/python-3.12-blue.svg) \n[![PyPI version](https://badge.fury.io/py/ontocast.svg)](https://badge.fury.io/py/ontocast)\n[![PyPI Downloads](https://static.pepy.tech/badge/ontocast)](https://pepy.tech/projects/ontocast)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![pre-commit](https://github.com/growgraph/ontocast/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/growgraph/ontocast/actions/workflows/pre-commit.yml)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17796467.svg)](https://doi.org/10.5281/zenodo.17796467)\n\n---\n\n## Overview\n\nOntoCast is a framework for extracting semantic triples (creating a Knowledge Graph) from documents using an agentic, ontology-driven approach. It combines ontology management, natural language processing, and knowledge graph serialization to turn unstructured text into structured, queryable data.\n\n---\n\n## Key Features\n\n- **Ontology-Guided Extraction**: Ensures semantic consistency and co-evolves ontologies\n- **Entity Disambiguation**: Resolves references across document chunks\n- **Multi-Format Support**: Handles text, JSON, PDF, and Markdown\n- **Semantic Chunking**: Splits text based on semantic similarity\n- **MCP Compatibility**: Implements Model Control Protocol endpoints\n- **RDF Output**: Produces standardized RDF/Turtle\n- **Triple Store Integration**: Supports Neo4j (n10s) and Apache Fuseki\n- **Hierarchical Configuration**: Type-safe configuration system with environment variable support\n- **CLI Parameters**: Flexible command-line interface with `--skip-ontology-critique` option\n- **Automatic LLM Caching**: Built-in response caching for improved performance and cost reduction\n- **GraphUpdate Operations**: Token-efficient SPARQL-based updates instead of full graph regeneration\n- **Budget Tracking**: Comprehensive tracking of LLM usage and triple generation metrics\n- **Ontology Versioning**: Automatic semantic versioning with hash-based lineage tracking\n\n---\n\n## Applications\n\nOntoCast can be used for:\n\n- **Knowledge Graph Construction**: Build domain-specific or general-purpose knowledge graphs from documents\n- **Semantic Search**: Power search and retrieval with structured triples\n- **GraphRAG**: Enable retrieval-augmented generation over knowledge graphs (e.g., with LLMs)\n- **Ontology Management**: Automate ontology creation, validation, and refinement\n- **Data Integration**: Unify data from diverse sources into a semantic graph\n\n---\n\n## Installation\n\n```sh\nuv add ontocast \n# or\npip install ontocast\n```\n\n---\n\n## Quick Start\n\n### 1. Configuration\n\nCreate a `.env` file with your configuration:\n\n```bash\n# LLM Configuration\nLLM_PROVIDER=openai\nLLM_API_KEY=your-api-key-here\nLLM_MODEL_NAME=gpt-4o-mini\nLLM_TEMPERATURE=0.1\n\n# Server Configuration\nPORT=8999\nMAX_VISITS=3\nRECURSION_LIMIT=1000\nESTIMATED_CHUNKS=30\nONTOLOGY_MAX_TRIPLES=10000\n\n# Path Configuration\nONTOCAST_WORKING_DIRECTORY=/path/to/working\nONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontologies\nONTOCAST_CACHE_DIR=/path/to/cache\n\n# Optional: Triple Store Configuration\nFUSEKI_URI=http://localhost:3032/test\nFUSEKI_AUTH=admin:password\nFUSEKI_DATASET=ontocast\n\n# Optional: Skip ontology critique\nSKIP_ONTOLOGY_DEVELOPMENT=false\n# Optional: Maximum triples allowed in ontology graph (set empty for unlimited)\nONTOLOGY_MAX_TRIPLES=10000\n```\n\n### 2. Start Server\n\n```bash\nontocast \\\n    --env-path .env \\\n    --working-directory /path/to/working \\\n    --ontology-directory /path/to/ontologies\n```\n\n### 3. Process Documents\n\n```bash\ncurl -X POST http://localhost:8999/process -F \"file=@document.pdf\"\n```\n\n### 4. API Endpoints\n\nThe OntoCast server provides the following endpoints:\n\n- **POST /process**: Process documents and extract semantic triples\n  ```bash\n  curl -X POST http://localhost:8999/process -F \"file=@document.pdf\"\n  ```\n\n- **POST /flush**: Flush/clean triple store data\n  ```bash\n  # Clean all datasets (Fuseki) or entire database (Neo4j)\n  curl -X POST http://localhost:8999/flush\n  \n  # Clean specific Fuseki dataset\n  curl -X POST \"http://localhost:8999/flush?dataset=my_dataset\"\n  ```\n  **Note:** For Fuseki, you can specify a `dataset` query parameter to clean a specific dataset. If omitted, all datasets are cleaned. For Neo4j, the `dataset` parameter is ignored and all data is deleted.\n\n- **GET /health**: Health check endpoint\n- **GET /info**: Service information endpoint\n\n---\n\n\n## LLM Caching\n\nOntoCast includes automatic LLM response caching to improve performance and reduce API costs. Caching is enabled by default and requires no configuration.\n\n### Cache Locations\n\n- **Tests**: `.test_cache/llm/` in the current working directory\n- **Windows**: `%USERPROFILE%\\AppData\\Local\\ontocast\\llm\\`\n- **Unix/Linux**: `~/.cache/ontocast/llm/` (or `$XDG_CACHE_HOME/ontocast/llm/`)\n\n### Benefits\n\n- **Faster Execution**: Repeated queries return cached responses instantly\n- **Cost Reduction**: Identical requests don't hit the LLM API\n- **Offline Capability**: Tests can run without API access if responses are cached\n- **Transparent**: No configuration required - works automatically\n\n### Custom Cache Directory\n\nIf you need to specify a custom cache directory:\n\n```python\nfrom pathlib import Path\nfrom ontocast.tool.llm import LLMTool\n\n# Cache directory is managed automatically by Cacher\nllm_tool = LLMTool.create(\n    config=llm_config\n)\n```\n\n\n## Configuration System\n\nOntoCast uses a hierarchical configuration system built on Pydantic BaseSettings:\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `LLM_API_KEY` | API key for LLM provider | - | Yes |\n| `LLM_PROVIDER` | LLM provider (openai, ollama) | openai | No |\n| `LLM_MODEL_NAME` | Model name | gpt-4o-mini | No |\n| `LLM_TEMPERATURE` | Temperature setting | 0.1 | No |\n| `ONTOCAST_WORKING_DIRECTORY` | Working directory path | - | Yes |\n| `ONTOCAST_ONTOLOGY_DIRECTORY` | Ontology files directory | - | No |\n| `PORT` | Server port | 8999 | No |\n| `MAX_VISITS` | Maximum visits per node | 3 | No |\n| `SKIP_ONTOLOGY_DEVELOPMENT` | Skip ontology critique | false | No |\n| `ONTOLOGY_MAX_TRIPLES` | Maximum triples allowed in ontology graph | 10000 | No |\n| `SKIP_FACTS_RENDERING` | Skip facts rendering and go straight to aggregation | false | No |\n| `ONTOCAST_CACHE_DIR` | Custom cache directory for LLM responses | Platform default | No |\n\n### Triple Store Configuration\n\n```bash\n# Fuseki (Preferred)\nFUSEKI_URI=http://localhost:3032/test\nFUSEKI_AUTH=admin:password\nFUSEKI_DATASET=dataset_name\n\n# Neo4j (Alternative)\nNEO4J_URI=bolt://localhost:7689\nNEO4J_AUTH=neo4j:password\n```\n\n### CLI Parameters\n\n```bash\n# Skip ontology critique step\nontocast --skip-ontology-critique\n\n# Process only first N chunks (for testing)\nontocast --head-chunks 5\n\n```\n\n---\n\n## Triple Store Setup\n\nOntoCast supports multiple triple store backends with automatic fallback:\n\n1. **Apache Fuseki** (Recommended) - Native RDF with SPARQL support\n2. **Neo4j with n10s** - Graph database with RDF capabilities  \n3. **Filesystem** (Fallback) - Local file-based storage\n\nWhen multiple triple stores are configured, **Fuseki is preferred over Neo4j**.\n\n### Quick Setup with Docker\n\n**Fuseki:**\n```bash\ncd docker/fuseki\ncp .env.example .env\n# Edit .env with your values\ndocker compose --env-file .env fuseki up -d\n```\n\n**Neo4j:**\n```bash\ncd docker/neo4j\ncp .env.example .env\n# Edit .env with your values\ndocker compose --env-file .env neo4j up -d\n```\n\nSee [Triple Store Setup](docs/user_guide/triple_stores.md) for detailed instructions.\n\n---\n\n## Documentation\n\n- [Quick Start Guide](docs/getting_started/quickstart.md) - Get started quickly\n- [Configuration System](docs/user_guide/configuration.md) - Detailed configuration guide\n- [Triple Store Setup](docs/user_guide/triple_stores.md) - Triple store configuration\n- [User Guide](docs/user_guide/concepts.md) - Core concepts and workflow\n- [API Reference](docs/reference/onto.md) - Detailed API documentation\n\n---\n\n## Recent Changes\n\n### Ontology Management Improvements\n\n- **Automatic Versioning**: Semantic version increment based on change analysis (MAJOR/MINOR/PATCH)\n- **Hash-Based Lineage**: Git-style versioning with parent hashes for tracking ontology evolution\n- **Multiple Version Storage**: Versions stored as separate named graphs in Fuseki triple stores\n- **Timestamp Tracking**: `updated_at` field tracks when ontology was last modified\n- **Smart Version Analysis**: Analyzes ontology changes (classes, properties, instances) to determine appropriate version bump\n\n### GraphUpdate System\n\n- **Token Efficiency**: LLM outputs structured SPARQL operations (insert/delete) instead of full TTL graphs\n- **Incremental Updates**: Only changes are generated, dramatically reducing token usage\n- **Structured Operations**: TripleOp operations with explicit prefix declarations for precise updates\n- **SPARQL Generation**: Automatic conversion of operations to executable SPARQL queries\n\n### Budget Tracking\n\n- **LLM Statistics**: Tracks API calls, characters sent/received for cost monitoring\n- **Triple Metrics**: Tracks ontology and facts triples generated per operation\n- **Summary Reports**: Budget summaries logged at end of processing\n- **Integrated Tracking**: Budget tracker integrated into AgentState for clean dependency injection\n\n### Configuration System Overhaul\n\n- **Hierarchical Configuration**: New `ToolConfig` and `ServerConfig` structure\n- **Environment Variables**: Support for `.env` files and environment variables\n- **Type Safety**: Full type safety with Python 3.12 union syntax\n- **API Key**: Changed from `OPENAI_API_KEY` to `LLM_API_KEY` for consistency\n- **Dependency Injection**: Removed global variables, implemented proper DI\n\n### Enhanced Features\n\n- **CLI Parameters**: New `--skip-ontology-critique` and `--skip-facts-rendering` parameters\n- **RDFGraph Operations**: Improved `__iadd__` method with proper prefix binding\n- **Triple Store Management**: Better separation between filesystem and external stores\n- **Serialization Interface**: Unified `serialize()` method for storing Ontology and RDFGraph objects\n- **Error Handling**: Improved error handling and validation\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete details.\n\n---\n\n## Examples\n\n### Basic Usage\n\n```python\nfrom ontocast.config import Config\nfrom ontocast.toolbox import ToolBox\n\n# Load configuration\nconfig = Config()\n\n# Initialize tools\ntools = ToolBox(config)\n\n# Process documents\n# ... (use tools for processing)\n```\n\n### Server Usage\n\n```bash\n# Start server with custom configuration\nontocast \\\n    --env-path .env \\\n    --working-directory /data/working \\\n    --ontology-directory /data/ontologies \\\n    --skip-ontology-critique \\\n    --head-chunks 10\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.\n\n---\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Support\n\n- **Documentation**: [docs/](docs/)\n- **Issues**: [GitHub Issues](https://github.com/growgraph/ontocast/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/growgraph/ontocast/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrowgraph%2Fontocast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrowgraph%2Fontocast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrowgraph%2Fontocast/lists"}