OntoCast

Summary

OntoCast is an open-source vector-db-rag tool that agents can use to extract RDF knowledge graphs from documents by co-evolving domain ontologies and fact graphs using a map/reduce pipeline. The tool is licensed under Apache 2.0 and can be run as a REST service, a batch CLI, or embedded within a LangChain/LangGraph agent. It is intended for application developers and positions itself as an alternative to document processing pipelines that require multiple complex integrations. The project has active documentation and a DOI.

Agentic Ontology Assisted Framework for Semantic Triple Extraction

Command line

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

1. docs update Aug 29, 2026 · issue 010

   OntoCast gains finalize_update_report and log_quarantine in ontocast.agent.update_common for shared graph-patch hygiene.

   └──▷ USE IT
   Finalize an LLM-rendered patch with a custom domain repair hook, then inspect which triples were quarantined before writing the update to the graph store.
   python copy

   from ontocast.agent.update_common import finalize_update_report, log_quarantine
   
   # report is a GraphUpdateRenderReport returned by a render agent
   update, rejected = finalize_update_report(report, insert_hook=my_domain_repair)
   log_quarantine('facts', rejected)
   # rejected is a list[RejectedLiteralTriple] — inspect or persist before applying update

   • ›Adds finalize_update_report(report, *, insert_hook=None) in ontocast.agent.update_common to canonicalize prefixes, quarantine malformed XSD typed literals, and run optional domain repairs on insert triples before a patch is applied — returning a tuple[GraphUpdate, list[RejectedLiteralTriple]].
   • ›Adds optional insert_hook parameter to finalize_update_report — a caller-supplied InsertHook that receives only the insert graph (not the delete side) for domain-specific triple repair, with its rejections merged into the quarantine list.
   • ›Adds log_quarantine(kind, rejected) in ontocast.agent.update_common to emit a single warning per render cycle whenever triples carrying invalid literals are withheld from the applied graph.
2. docs update Aug 29, 2026 · issue 010

   OntoCast adds a dedicated SHACLSHACLA W3C standard language for defining constraints and validation rules over RDF graphs, allowing a tool to verify that graph-structured data conforms to a declared shape or schema. shapes dataset partition with FACTS_SHAPES_DIR, POST /shapes, and DELETE routes

   └──▷ TRY IT
   Seed a directory of SHACL shapes into the shapes partition so they reload on every restart during development.
   copy

   $ FUSEKI_SHAPES_DATASET=ontocast--test--shapes
   FACTS_SHAPES_DIR=/path/to/seed/shapes

   • ›Adds FACTS_SHAPES_DIR environment variable to seed SHACL shapes documents into a dedicated shapes partition on every startup (recursive scan, overwrites on each restart so edits take effect immediately).
   • ›Adds POST /shapes and matching DELETE endpoints to mutate the shapes store independently of the ontologies dataset.
   • ›Introduces a third triple-store dataset ({tenant}--{project}--shapes) to isolate SHACL shapes from the ontologies partition, preventing shapes documents from being vector-indexed or surfaced as schema ontologies.
   • ›Adds store keyword argument to aselect(query, *, store='ontologies') and aconstruct(query, *, store='ontologies') to target a specific dataset partition.
3. docs update Aug 29, 2026 · issue 010

   OntoCast adds SHACLSHACLA W3C standard language for defining constraints and validation rules over RDF graphs, allowing a tool to verify that graph-structured data conforms to a declared shape or schema.-backed validation, literal deduplication, ontology delta shadow mode, and per-document critic telemetry across facts and ontology loops.

   └──▷ TRY IT
   Drop the shapes partition along with facts and ontologies during a full flush, rather than retaining the validation contract.
   copy

   $ curl -X POST 'https://<host>/flush?include_shapes=true'

   • ›Adds FACTS_ACCEPT_BLOCKING_SEVERITY (default critical) to control which TripleFix severity level blocks render acceptance, replacing the previous score-only gate.
   • ›Adds FACTS_ADDITIONAL_STANDARD_NAMESPACES config to extend the closed-namespace allow-list used by UNKNOWN_TERM mandatory findings.
   • ›Adds FACTS_QUANTITY_FALLBACK_VOCABULARY config to name the quantity fallback vocabulary, exempting it from unknown-term flagging and repair-deletion.
   • ›Adds FACTS_LITERAL_VARIANT_DEDUPE (default on) to collapse duplicate literals that differ only in language tag or datatype on the same (subject, predicate), with the language-tagged form winning; each removal is recorded as a literal_variant_pruned repair record.
   • ›Adds ONTOCAST_ONTOLOGY_DIRECTORY-style bootstrap contract for SHACL shapes: shapes are seeded from a directory at startup and stored in a per-tenant {tenant}--{project}--shapes partition in the triple store, making them addressable and mutable via /shapes.
   +10 moreshow less

   • ›Adds POST /flush?include_shapes=true parameter to drop the shapes partition on flush; without it, POST /flush retains shapes by default (subsequent runs report shacl_evaluated: null if shapes are absent).
   • ›Adds ONTOLOGY_CONTEXT_MODE=selected_vector_search_ontology setting to enable vector-search-based per-unit snapshot retrieval with reduce-time reconciliation policies.
   • ›Adds ONTOLOGY_RECONCILE_MINTED_TERMS policy (default detect; also supports substitute and disable) to reconcile re-minted ontology terms against catalog terminals at reduce time.
   • ›Adds ontology delta shadow-mode validation (deterministic lane against insert/delete delta only, never the full graph), running checks including foreign_namespace, degenerate_restriction, missing_label, subclass_cycle, role_confusion, cardinality_contradiction, foreign_delete, and advisory label_collision.
   • ›Adds LABEL_ONLY_NUMBER mandatory finding, firing when a node carries the fallback vocabulary's unit property but has no numeric literal on any property while its label holds a number as prose.
   • ›Adds MIXED_OBJECT_KINDS finding with three branches: ≥2 distinct canonical numeric values, ≥2 irreconcilable short string values, or ≥2 IRI objects on a dominantly single-valued predicate.
   • ›Adds degenerate-bound promotion: equal lower/upper bounds collapse to a scalar on the configured numeric_value property when lower_bound and upper_bound roles match.
   • ›Writes per-document ontology critic telemetry to the run manifest under ontology_critic and exposes ontology_findings_residual, ontology_mandatory_residual, ontology_critic_calls, and ontology_critic_accepted in retrieval_metrics.
   • ›Exposes reduce-time metrics minted_duplicates, minted_duplicate_pairs, minted_duplicates_rewritten, deletes_dropped_unredeclared, fresh_ontologies_merged, fresh_minted_duplicates, apply_deletes_no_match, unattributed_insert_triples, and unattributed_delete_triples for ontology delta tracking.
   • ›SHACL shapes are cross-checked against term-validator rules at load time, logging an error for any property that shapes require but the term validator would flag as unknown.
4. docs update Aug 29, 2026 · issue 010

   OntoCast aggregation gains named guard flags, natural-key merge, cluster-wide vetoes, and structured merge-refusal codes

   └──▷ TRY IT
   Disable the initials guard to allow merges between entities like 'company S.' and 'company T.' when your corpus legitimately uses initials as abbreviations for the same entity.
   copy

   $ AGG_INITIALS_DISTINCT_GUARD=false

   Enable strict typed-vs-untyped merge rejection to harden entity resolution when untyped nodes should never absorb typed ones.
   copy

   $ AGG_TYPE_GUARD_UNTYPED=strict

   • ›Adds AGG_LITERAL_CONFLICT_GUARD config flag (default true) to veto merges between entities asserting disjoint literal values on a shared predicate, with refusals counted in facts_rejected_merges.
   • ›Adds AGG_INITIALS_DISTINCT_GUARD config flag (default true) to veto merges between entities whose labels are identical except for conflicting initials (e.g. 'company S.' vs 'company T.').
   • ›Adds AGG_NATURAL_KEY_MERGE config flag (default true) to treat instances sharing an identical short string value on a single-valued identifier-like predicate as merge candidates, even when labels and embeddings disagree.
   • ›Adds AGG_TYPE_GUARD_UNTYPED config flag (default permissive) controlling whether a typed entity may merge with an untyped one; strict fails typed-vs-untyped pairs.
   • ›Introduces cluster-wide veto semantics: a vetoed pair blocks transitive closure, so a guard refusal cannot be bypassed through a chain of accepted edges.
   +3 moreshow less

   • ›Exposes structured merge-refusal reason codes — literal_conflict, functional_iri_conflict, initials_conflict, role, type, lexical, and cluster_veto — logged alongside facts_rejected_merges to let practitioners trace which guard split a surprising cluster.
   • ›Key-supported clusters (formed via AGG_NATURAL_KEY_MERGE) are now reported on AggregationResult as key_supported_clusters and carried on AgentState as aggregation_key_clusters.
   • ›Downgrades SUSPECT_MULTI_VALUE string findings from error to warning on key-supported subjects during SHACL validation, preventing the un-merge repair loop from splitting correctly merged entities.
5. docs update Aug 29, 2026 · issue 010

   OntoCast adds per-tenant SHACLSHACLA W3C standard language for defining constraints and validation rules over RDF graphs, allowing a tool to verify that graph-structured data conforms to a declared shape or schema. shapes partitioning with FUSEKI_SHAPES_DATASET and FACTS_SHAPES_DIR controls

   └──▷ TRY IT
   Upload SHACL shapes scoped to a specific tenant and project partition in Fuseki.
   copy

   $ curl -X POST "http://localhost:8999/shapes?tenant=acme&project=reports" -F "[email protected]"

   • ›Adds a {tenant}--{project}--shapes triple-store dataset partition for SHACL shapes, isolated per tenant and project (no vector-store counterpart, as shapes are never retrieved by similarity).
   • ›New FACTS_SHAPES_DIR config key sets the source directory for a tenant's SHACL shapes on initialisation; an empty partition is valid and is read downstream as 'SHACL never checked' rather than 'conforms'.
   • ›Supports tenant and project query parameters on the shapes upload endpoint (http://localhost:8999/shapes?tenant=<tenant>&project=<project>) to scope shape uploads to a specific partition.
   • ›Adds &include_shapes=true query parameter to the flush endpoint to optionally drop shapes alongside partition data (default flush retains shapes).
6. docs update Aug 29, 2026 · issue 010

   OntoCast adds SHACLSHACLA W3C standard language for defining constraints and validation rules over RDF graphs, allowing a tool to verify that graph-structured data conforms to a declared shape or schema. shapes partition management via GET/POST/DELETE /shapes endpoints and include_shapes reset flag

   └──▷ TRY IT
   Upload a SHACL shapes file to activate the validation gate for a tenant/project.
   copy

   $ curl -X POST "http://localhost:8999/shapes?tenant=ontocast&project=test" -F "file=@my_shapes.ttl"

   Remove a specific shapes document by graph URI when retiring an old SHACL constraint set.
   copy

   $ curl -X DELETE "http://localhost:8999/shapes/http%3A%2F%2Fexample.org%2Fmy-shapes?tenant=ontocast&project=test"

   Confirm the current shapes partition contents and merged triple count before a validation run.
   copy

   $ curl "http://localhost:8999/shapes?tenant=ontocast&project=test"

   • ›Adds GET /shapes endpoint to list named graphs in the shapes partition and return the merged triple count.
   • ›Adds POST /shapes endpoint to upload a SHACL shapes document (Turtle file); documents with <iri> a owl:Ontology are stored under that IRI (re-upload replaces), and headerless documents are named after the uploaded filename.
   • ›Adds DELETE /shapes/{graph_uri} endpoint to remove a shapes document by URL-encoded graph URI; the seed directory (FACTS_SHAPES_DIR) is untouched, so seeded documents return on next restart.
   • ›Adds include_shapes parameter to the reset/rerun flow to also drop the shapes partition; off by default — omitting it means a rerun restores facts and ontologies but leaves SHACL disabled, reporting shacl_evaluated: null instead of failing.
   • ›Introduces a dedicated shapes partition separate from the ontologies dataset, so the SHACL validation gate operates against its own named-graph store.
7. docs update Aug 29, 2026 · issue 010

   OntoCast adds FACTS_ACCEPT_BLOCKING_SEVERITY config key and a deterministic ontology-finding lane running in shadow mode

   └──▷ TRY IT
   Widen the facts acceptance gate to also block on 'important'-severity critic fixes, catching more issues before a unit exits the loop.
   copy

   $ FACTS_ACCEPT_BLOCKING_SEVERITY=important

   • ›Adds FACTS_ACCEPT_BLOCKING_SEVERITY config key to control which critic-fix severities block a facts unit from leaving the loop; accepted values are critical (default), important, and never.
   • ›Introduces a deterministic finding lane for the ontology loop (tool/ontology_validation/unit_findings.py) running in shadow mode: findings are collected, injected into the critic prompt as MANDATORY items, and reported as ontology_findings_residual / ontology_mandatory_residual without changing the gate.
8. docs update Aug 29, 2026 · issue 010

   OntoCast adds AGG_CANDIDATE_SIMILARITY_THRESHOLD configuration with a default of .70

   • ›Adds AGG_CANDIDATE_SIMILARITY_THRESHOLD environment variable (default 0.70) to control the similarity threshold for aggregation candidate selection.
9. v0.6.2 Aug 29, 2026 · issue 011

   OntoCast v0.6.2 adds a /shapes API, per-tenant SHACLSHACLA W3C standard language for defining constraints and validation rules over RDF graphs, allowing a tool to verify that graph-structured data conforms to a declared shape or schema. shape storage, and a selective flush with include_shapes.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.6.2 https://github.com/growgraph/ontocast.git
   # already have the repo? check out this version:
   $ git checkout v0.6.2

   └──▷ TRY IT
   Flush everything including shapes (e.g. to fully reset a CI environment between test suites).
   copy

   $ curl -X POST 'https://ontocast.example.com/flush?include_shapes=true'

   • ›Adds /shapes REST routes — GET (list stored documents), POST (upload Turtle), and DELETE /{graph_uri} — mirroring /ontologies and tenancy-scoped the same way; a document declaring <iri> a owl:Ontology is stored under that IRI so re-uploading replaces it.
   • ›Adds POST /flush?include_shapes=true to optionally drop the shapes partition on flush; by default flush retains shapes, and later runs report shacl_evaluated: null instead of failing when shapes are absent.
   • ›Adds include_shapes flag to TripleStoreManager.clean() and clean_tenancy() to control whether the SHACL shapes partition is cleared.
   • ›SHACL shapes are now stored in the triple store in a dedicated {tenant}--{project}--shapes partition (FUSEKI_SHAPES_DATASET), enabling per-tenant shape catalogs and removing the need for a shapes directory in containerised workers.
   • ›Changes FACTS_SHAPES_DIR from a live read directory to a read-only seed materialized into the shapes partition at startup; the validation gate now reads the partition rather than the directory.
   +4 moreshow less

   • ›Adds tool/shapes_catalog.py and api/shapes.py as new modules supporting shape catalog discovery and the /shapes API.
   • ›Replaces the two-valued use_ontologies_dataset: bool parameter on aselect, aconstruct, drop_named_graph, drop_all_ontology_graphs_for_iri, serialize_graph, and serialize with a StoreKind ("facts" | "ontologies" | "shapes") partition selector.
   • ›Updates the LangChain tools ontocast_sparql_select and ontocast_sparql_construct to expose a store parameter in place of use_ontologies_dataset.
   • ›Flattens the ontology update wire: GraphUpdateRenderReport now carries insert_graph and delete_graph as sibling fields, and to_graph_update() compiles them delete-then-insert for apply(), the SPARQL compiler, and the LangChain tool.
   └──▷ BREAKING ON UPGRADE

   • !GraphUpdateRenderReport replaces graph_update.triple_operations[] with sibling fields insert_graph and delete_graph; interleaving inserts and deletes within a single render is no longer expressible, and cached ontology-render responses are invalidated. Touches onto/model.py::GraphUpdateRenderReport, to_graph_update, prompt/graph_format.py, prompt/llm_json_schema.py.
   • !tool/facts_invariants.py is removed; the previous module name no longer resolves. Replace all imports with tool/facts_validation/ (public surface via package __init__).
   • !The data/ top-level directory and its importable data package are removed. TTL fixtures are now in test/data/ontologies/; local-source entries in run/fetch_schema_samples.py resolve via ONTOCAST_SCHEMA_SAMPLE_DIR and are skipped when unset.
   • !FACTS_SHAPES_DIR changes meaning from a live read directory to a read-only seed; the validation gate now reads the {tenant}--{project}--shapes triple-store partition (FUSEKI_SHAPES_DATASET). A containerised worker that relied on the directory for validation must migrate shapes to the store.
   • !collect_shacl_shapes(ontology_graph, shapes_dir) signature changes to collect_shacl_shapes(ontology_graph, stored_shapes: RDFGraph | None); it no longer performs disk I/O.
   • !The use_ontologies_dataset: bool parameter is removed from aselect, aconstruct, drop_named_graph, drop_all_ontology_graphs_for_iri, serialize_graph, and serialize; callers must switch to the store: StoreKind ("facts" | "ontologies" | "shapes") parameter. The LangChain tools ontocast_sparql_select and ontocast_sparql_construct likewise replace use_ontologies_dataset with store.
   • !aserialize(ontology) previously hard-coded the ontologies dataset and silently overwrote a caller's graph_uri; it now honours a store= override, so callers relying on the silent override must pass store='ontologies' explicitly.
10. v0.6.1 Aug 10, 2026 · issue 004

    OntoCast v0.6.1 adds ONTOLOGY_CONTEXT_MAX_TRIPLES prompt cap, changes LLM_GRAPH_FORMAT default to jsonld, and introduces seed-free graph pruning in graph_prune.py.

    └──▷ GET THIS VERSION
    copy

    $ git clone --branch v0.6.1 https://github.com/growgraph/ontocast.git
    # already have the repo? check out this version:
    $ git checkout v0.6.1

    └──▷ TRY IT
    Cap how many triples reach the LLM prompt to stay within a provider's context window, without truncating load-bearing schema.
    copy

    $ ONTOLOGY_CONTEXT_MAX_TRIPLES=2000 python -m ontocast.server

    Keep Turtle as the LLM wire format for providers whose structured-output handling works better with plain strings than nested JSON-LD objects.
    copy

    $ LLM_GRAPH_FORMAT=turtle python -m ontocast.server

    • ›Adds ONTOLOGY_CONTEXT_MAX_TRIPLES (default 4000) to bound ontology context size in every prompt mode — selected_single_ontology, fixed_single_ontology, and facts fan-out — enforced at format_ontology_chapter; over budget, onto/ontology_condense.py drops triples in increasing order of harm (header/list noise first, redundant structure second, glosses third) and never drops labels, types, hierarchy, or domain/range.
    • ›Changes LLM_GRAPH_FORMAT default from Turtle to jsonld across ServerConfig, AgentState, UnitState, and the llm_graph_format_ctx ContextVar; Turtle remains supported via explicit configuration.
    • ›Changes ONTOLOGY_MAX_TRIPLES default to unlimited; the variable is still available as a runaway-growth backstop on the per-unit working graph — use ONTOLOGY_CONTEXT_MAX_TRIPLES to cap prompt size instead.
    • ›Adds ONTOLOGY_SNAPSHOT_TRIPLES retrieval metric, now written for every context mode (previously only the vector resolver recorded a size under patch_retrieval).
    • ›Moves seed-free graph pruners and predicate vocabularies (NOISY_EXPANSION_PREDICATES, GENERIC_INDIVIDUAL_TYPES, MIN_MEANINGFUL_RESTRICTION_PREDICATES, OWL_RESTRICTION_MEANINGFUL_PREDICATES, bfs_triple_rank, count_meaningful_restriction_predicates, prune_degenerate_restriction_bnodes, prune_orphaned_bnode_subjects, remove_bnode_subgraph) into the new shared module onto/graph_prune.py, reusable by both induced-subgraph retrieval and the prompt condenser.
    +1 moreshow less

    • ›The ontocast_extract LangChain/MCP tool now reads its render_mode default from the RENDER_MODE environment variable (via parse_render_mode_param) instead of hardcoding ontology_and_facts.
    └──▷ BREAKING ON UPGRADE

    • !LLM_GRAPH_FORMAT now defaults to jsonld; any deployment that never set this variable will switch wire format on upgrade. Set LLM_GRAPH_FORMAT=turtle explicitly to preserve the previous behaviour.
    • !ONTOLOGY_MAX_TRIPLES now defaults to unlimited (was 50000); workloads relying on the old cap to bound working-graph growth must set the variable explicitly.
11. v0.6.0 Aug 9, 2026 · issue 004

    OntoCast v0.6.0 adds a LangChain integration module and first PyPI publication since v0.4.3.

    └──▷ GET THIS VERSION
    copy

    $ git clone --branch v0.6.0 https://github.com/growgraph/ontocast.git
    # already have the repo? check out this version:
    $ git checkout v0.6.0

    └──▷ USE IT
    Wire OntoCast's ontology and retrieval capabilities into a LangChain agent, with write operations enabled.
    python copy

    from ontocast import Config, ToolBox, ontocast_tools
    from langchain.agents import create_agent
    
    tools = await ToolBox.acreate(Config.in_memory())
    await tools.initialize()
    
    agent = create_agent(model, tools=[*ontocast_tools(tools, mutating=True)])

    Diagnose which OntoCast tools were excluded from the LangChain toolset due to missing backends.
    python copy

    from ontocast import Config, ToolBox
    from ontocast.integrations.langchain import ontocast_tool_diagnostics
    
    tools = await ToolBox.acreate(Config.in_memory())
    await tools.initialize()
    
    print(ontocast_tool_diagnostics(tools))

    • ›Adds ontocast.integrations.langchain module exposing ontocast_tools(tools), which returns a list of BaseTool objects any LangChain or LangGraph agent can call, with capability-gated tool inclusion and opt-in mutation via mutating=True.
    • ›Adds ontocast_tool_diagnostics function to explain which tools were omitted from the LangChain toolset and why, making missing-backend failures visible.
    • ›Introduces ExternalEvidenceCacheEntry as the supported replacement for UnitState external-evidence mirrors.
    • ›Introduces ontocast.onto.constants.PROVENANCE_METADATA_TERMS, a module-level frozenset naming the classes and predicates the pipeline mints on provenance nodes, replacing the former class attribute TripleStoreManager._PROVENANCE_METADATA_PREDICATES.
    • ›First release published to PyPI since v0.4.3; v0.5.0 and v0.5.1 were in-tree version bumps never tagged or published.
    └──▷ BREAKING ON UPGRADE

    • !Removed in-memory vector store: VECTOR_STORE_BACKEND=memory, VectorStoreBackend.MEMORY, and tool/vector_store/in_memory.py are gone; retrieval now requires Qdrant or LanceDB. Config.in_memory() is triple-store only (pyoxigraph).
    • !AtomicToolBox now takes WebSearchConfig and EmbeddingBasedAggregator now takes AggregationConfig; flat kwargs are removed from both.
    • !Removed test-api console script and cli/test_api.py; requests is dropped from the server extra.
    • !Removed cmp-states console script and ontocast/cli/cmp_states.py.
    • !A provenance unit node is now typed schema:Text (the class) instead of schema:text (a property IRI); graphs already in a triple store keep the old type until re-extracted, and any query filtering on schema:text must be updated.
    • !TripleStoreManager._PROVENANCE_METADATA_PREDICATES is removed; use ontocast.onto.constants.PROVENANCE_METADATA_TERMS instead.
    • !Removed dead modules onto/context.py, tool/graph_version_manager.py, and tool/graph_diff.py (~1,222 lines).
    • !Removed numerous previously import-visible symbols including route_after_convert, route_after_ontology_consolidation, WorkflowNode.AGGREGATE_FACTS, WorkflowNode.PARALLEL_MAP_UNITS, aggregate_anchor_metrics, URIPromoter, OntologyDecision, FactsDecision, CHUNK_NULL_IRI, render_ontology_rank_diagnostics, set_failure (no longer takes success_score), graph_uri_override, ToolBox._unlink_ttl_files_if_ontology_iri, and others; anything importing them out-of-tree breaks.
    • !ontology_directory is now strictly read-only: ingest_ontology_ttl no longer requires or touches it, and delete_ontology_by_iri no longer removes files from it. An ingested ontology lives only in the triple store and vector index and does not survive a rebuild from seeds.
    • !Dropped AgentState fields including UnitState shadows, never-read writers, and graph_uri_override; graph_uri is always doc_namespace.