# π§ Semantica
**A Framework for Building Context Graphs and Decision Intelligence Layers for AI**
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/semantica/)
[](https://github.com/Hawksight-AI/semantica/releases/tag/v0.4.0)
[](https://pepy.tech/project/semantica)
[](https://github.com/Hawksight-AI/semantica/actions)
[](https://discord.gg/sV34vps5hH)
[](https://x.com/BuildSemantica)
### β Give us a Star Β· π΄ Fork us Β· π¬ Join our Discord Β· π¦ Follow on X
> **Transform Chaos into Intelligence. Build AI systems with context graphs, decision tracking, and advanced knowledge engineering that are explainable, traceable, and trustworthy β not black boxes.**
---
## The Problem
AI agents today are powerful but not trustworthy:
- β **No memory structure** β agents store embeddings, not meaning. There's no way to ask *why* something was recalled.
- β **No decision trail** β agents make decisions continuously but record nothing. When something breaks, there's no history to audit.
- β **No provenance** β outputs can't be traced back to source facts. In regulated industries, this is a hard compliance blocker.
- β **No reasoning transparency** β black-box answers with zero explanation of how a conclusion was reached.
- β **No conflict detection** β contradictory facts silently coexist in vector stores, producing unpredictable outputs.
These aren't edge cases. They're the reason AI can't be deployed in healthcare, finance, legal, and government without custom guardrails built from scratch every time.
## The Solution
Semantica is the **context and intelligence layer** you add on top of your existing AI stack:
- β
**Context Graphs** β a structured, queryable graph of everything your agent knows, decides, and reasons about.
- β
**Decision Intelligence** β every decision is tracked as a first-class object with causal links, precedent search, and impact analysis.
- β
**Full Provenance** β every fact links back to its source. W3C PROV-O compliant. No more mystery answers.
- β
**Reasoning Engines** β forward chaining, Rete networks, deductive, abductive, and SPARQL. Explainable paths, not black boxes.
- β
**Quality & Deduplication** β conflict detection, entity resolution, and pipeline validation built in.
> Works alongside LangChain, LlamaIndex, AutoGen, CrewAI, and any LLM β Semantica is the **accountability layer** on top, not a replacement.
```bash
pip install semantica
```
---
## Plugins (Claude, Cursor, Codex)
Semantica includes a cross-platform plugin bundle under `plugins/` for community use:
- 17 domain skills (context graphs, decision intelligence, explainability, reasoning, provenance, ontology, temporal, visualization)
- Specialized agents (`decision-advisor`, `explainability`, `kg-assistant`)
- Hook configuration and platform-specific manifests for Claude, Cursor, and Codex
See the community setup guide:
- [`plugins/.claude-plugin/README.md`](plugins/.claude-plugin/README.md)
---
## Features
### Context & Decision Intelligence
- **Context Graphs** β structured graph of entities, relationships, and decisions; queryable, causal, persistent
- **Decision tracking** β record, link, and analyze every agent decision with `add_decision()`, `record_decision()`
- **Causal chains** β link decisions with `add_causal_relationship()`, trace lineage with `trace_decision_chain()`
- **Precedent search** β hybrid similarity search over past decisions with `find_similar_decisions()`
- **Influence analysis** β `analyze_decision_impact()`, `analyze_decision_influence()` β understand downstream effects
- **Policy engine** β enforce business rules with `check_decision_rules()`; automated compliance validation
- **Agent memory** β `AgentMemory` with short/long-term storage, conversation history, and statistics
- **Cross-system context capture** β `capture_cross_system_inputs()` for multi-agent pipelines
### Knowledge Graphs
- **Knowledge graph construction** β entities, relationships, properties, typed edges
- **Graph algorithms** β PageRank, betweenness centrality, clustering coefficient, community detection
- **Node embeddings** β Node2Vec embeddings via `NodeEmbedder`
- **Similarity** β cosine similarity via `SimilarityCalculator`
- **Link prediction** β score potential new edges via `LinkPredictor`
- **Temporal graphs** β time-aware nodes and edges
- **Incremental / delta processing** β update graphs without full recompute
### Semantic Extraction
- **Entity extraction** β named entity recognition, normalization, classification
- **Relation extraction** β triplet generation from raw text using LLMs or rule-based methods
- **LLM-typed extraction** β extraction with typed relation metadata
- **Deduplication v1** β Jaro-Winkler similarity, basic blocking
- **Deduplication v2** β `blocking_v2`, `hybrid_v2`, `semantic_v2` strategies with `max_candidates_per_entity`
- **Triplet deduplication** β `dedup_triplets()` for removing duplicate (subject, predicate, object) triples
### Reasoning Engines
- **Forward chaining** β `Reasoner` with IF/THEN string rules and dict facts
- **Rete network** β `ReteEngine` for high-throughput production rule matching
- **Deductive reasoning** β `DeductiveReasoner` for classical inference
- **Abductive reasoning** β `AbductiveReasoner` for hypothesis generation from observations
- **SPARQL reasoning** β `SPARQLReasoner` for query-based inference over RDF graphs
### Provenance & Auditability
- **Entity provenance** β `ProvenanceTracker.track_entity(entity_id, source, metadata)`
- **Algorithm provenance** β `AlgorithmTrackerWithProvenance` tracks computation lineage
- **Graph builder provenance** β `GraphBuilderWithProvenance` records entity source lineage from URLs
- **W3C PROV-O compliant** β lineage tracking across all modules
- **Change management** β version control with checksums, audit trails, compliance support
### Vector Store
- **Backends** β FAISS, Pinecone, Weaviate, Qdrant, Milvus, PgVector, in-memory
- **Semantic search** β top-k retrieval by embedding similarity
- **Hybrid search** β vector + keyword with configurable weights
- **Filtered search** β metadata-based filtering on any field
- **Custom similarity weights** β tune retrieval per use case
### π Graph Database Support
- **AWS Neptune** β Amazon Neptune graph database with IAM authentication
- **Apache AGE** β PostgreSQL graph extension with openCypher via SQL
- **FalkorDB** β native support; `DecisionQuery` and `CausalChainAnalyzer` work directly with FalkorDB row/header shapes
### Data Ingestion
- **File formats** β PDF, DOCX, HTML, JSON, CSV, Excel, PPTX, archives
- **Web crawl** β `WebIngestor` with configurable depth
- **Databases** β `DBIngestor` with SQL query support
- **Snowflake** β `SnowflakeIngestor` with table/query ingestion, pagination, and key-pair/OAuth auth
- **Docling** β advanced document parsing with table and layout extraction (PDF, DOCX, PPTX, XLSX)
- **Media** β image OCR, audio/video metadata extraction
### Export Formats
- **RDF** β Turtle (`.ttl`), JSON-LD, N-Triples (`.nt`), XML via `RDFExporter`
- **Parquet** β `ParquetExporter` for entities, relationships, and full KG export
- **ArangoDB AQL** β ready-to-run INSERT statements via `ArangoAQLExporter`
- **OWL ontologies** β export generated ontologies in Turtle or RDF/XML
- **SHACL shapes** β export auto-derived constraint shapes via `RDFExporter.export_shacl()` (`.ttl`, `.jsonld`, `.nt`, `.shacl`)
### Pipeline & Production
- **Pipeline builder** β `PipelineBuilder` with stage chaining and parallel workers
- **Validation** β `PipelineValidator` returns `ValidationResult(valid, errors, warnings)` before execution
- **Failure handling** β `FailureHandler` with `RetryPolicy` and `RetryStrategy` (exponential backoff, fixed, etc.)
- **Parallel processing** β configurable worker count per pipeline stage
- **LLM providers** β 100+ models via LiteLLM (OpenAI, Anthropic, Cohere, Mistral, Ollama, and more)
### Ontology
- **Auto-generation** β derive OWL ontologies from knowledge graphs via `OntologyGenerator`
- **Import** β load existing OWL, RDF, Turtle, JSON-LD ontologies via `OntologyImporter`
- **Validation** β HermiT/Pellet compatible consistency checking
- **SHACL shape generation** β `OntologyEngine.to_shacl()` auto-derives SHACL node and property shapes from any Semantica ontology dict; zero hand-authoring; deterministic (same ontology β same shapes)
- **SHACL validation** β `OntologyEngine.validate_graph()` runs shapes against a data graph and returns a `SHACLValidationReport` with machine-readable violations and plain-English explanations
- **Quality tiers** β `"basic"` (structure + cardinality), `"standard"` (+ enumerations, inheritance), `"strict"` (+ `sh:closed` rejects undeclared properties)
- **Inheritance propagation** β child shapes automatically include all ancestor property shapes (up to 3+ levels), cycle-safe
- **Three output formats** β Turtle (`.ttl`), JSON-LD, N-Triples; file export via `export_shacl()`
## π What's New in v0.4.0
### π Temporal Intelligence Stack
Everything you need to reason about *when* β not just *what*.
- **Temporal GraphRAG** β retrieve knowledge as it existed at any point in the past. Natural-language queries like *"what did we know before the 2024 merger?"* are automatically parsed for temporal intent, with zero LLM calls.
- **Allen Interval Algebra** β 13 deterministic interval relations (before, meets, overlaps, during, starts, finishes, equals, and their converses). Find gaps, measure coverage, detect cycles β all without touching an LLM.
- **Point-in-time Query Engine** β reconstruct a self-consistent graph snapshot at any timestamp. Comes with a consistency validator that catches 5 classes of temporal errors: inverted intervals, dangling edges, overlapping relations, temporal gaps, and missing entities.
- **Temporal Metadata Extraction** β ask the LLM to annotate each extracted relation with `valid_from`, `valid_until`, and a calibrated confidence score (0β1 scale with baked-in anchors, so the model doesn't cluster near 1.0).
- **TemporalNormalizer** β converts ISO 8601, partial dates, relative phrases ("last year", "Q1 2024"), and 13 domain-specific phrase maps (Healthcare, Finance, Cybersecurity, Supply Chain, Energyβ¦) into UTC datetime pairs. Zero LLM calls.
- **Bi-temporal Provenance** β every provenance record is automatically stamped with transaction time. Full revision history and audit log export in JSON or CSV. Temporal relationships export as OWL-Time RDF triples.
- **Decision validity windows** β decisions now carry `valid_from` / `valid_until`. Superseded decisions stay in the graph β history is immutable. Point-in-time causal chain reconstruction included.
- **Named checkpoints** β snapshot the full agent context at any moment and diff two snapshots to see exactly what changed.
β [Temporal docs](docs/reference/) Β· [Temporal examples](cookbook/)
### π SKOS Vocabulary Management
Build and query controlled vocabularies inside your knowledge graph
- Add SKOS concepts with labels, alt-labels, broader/narrower hierarchy, and definitions β all required triples assembled automatically.
- Query and search vocabularies with SPARQL-backed APIs (injection-sanitized).
- REST API for the Explorer: list schemes, fetch full hierarchy trees (cycle-safe), and import `.ttl` / `.rdf` / `.owl` files.
β [SKOS docs](docs/reference/ontology.md)
### π· SHACL Constraints
Turn ontologies into executable data contracts β no hand-authoring.
- Auto-derive SHACL node and property shapes from any Semantica ontology. Deterministic: same ontology always produces the same shapes.
- Three strictness tiers: `"basic"` (structure + cardinality), `"standard"` (+ enumerations and inheritance), `"strict"` (closes shapes β rejects undeclared properties).
- Validate any RDF graph and get back a report with plain-English violation explanations ready to feed into an LLM or pipeline.
- Use in CI to catch breaking ontology changes before they reach production.
β SHACL shape generation and validation are available via the `OntologyEngine` β see [ontology docs](docs/reference/ontology.md)
### π§ Infrastructure & Fixes
- **ContextGraph pagination** β memory complexity dropped from O(N) to O(limit). A 50k-node graph no longer allocates 2.5M dicts per paginated request.
- **Named graph support** β full config-flag enforcement, duplicate clause prevention, backward-compat URI alias, and safe URI encoding in SPARQL pruning.
- **Ollama remote support** β `OllamaProvider` now correctly connects to remote Ollama servers instead of silently falling back to `localhost`.
- **Security** β API key logging removed from extractors; CI workflows locked to least-privilege `contents: read`.
β [Full changelog](CHANGELOG.md) Β· [Release notes](RELEASE_NOTES.md)
---
## π¦ What Was in v0.3.0
First stable `Production/Stable` release on PyPI.
- **Context Graphs** β temporal validity windows, weighted BFS, cross-graph navigation with full save/load persistence.
- **Decision Intelligence** β complete lifecycle from recording to impact analysis; `PolicyEngine` with versioned rules.
- **KG Algorithms** β PageRank, betweenness centrality, Louvain community detection, Node2Vec embeddings, link prediction.
- **Deduplication v2** β blocking/hybrid candidate generation **63.6% faster**; semantic dedup **6.98x faster**.
- **Delta Processing** β SPARQL-based incremental diff, `delta_mode` pipelines, snapshot versioning.
- **Export** β Parquet (Spark/BigQuery/Databricks ready), ArangoDB AQL, RDF format aliases.
- **Pipeline** β exponential/fixed/linear backoff, `PipelineValidator`, fixed retry loop.
- **Graph Backends** β Apache AGE (SQL injection fixed), AWS Neptune, FalkorDB, PgVector.
---
## β¨ What Semantica Does
### 𧩠Context & Decision Intelligence
Track every decision your agent makes as a structured, queryable graph node β with causal links, precedent search, impact analysis, and policy enforcement.
- Every decision records who made it, why, what outcome was chosen, and how confident.
- Decisions are linked causally so you can trace the full chain of reasoning that led to any outcome.
- Hybrid similarity search finds past decisions that match the current scenario.
- Policy rules validate decisions against business constraints before or after they're made.
- `AgentMemory` handles short/long-term storage and conversation history across sessions.
β [Decision tracking docs](docs/reference/) Β· [Decision tracking example](cookbook/)
### π Temporal Reasoning
Ask not just *what* your agent knows, but *when it was true*.
- Reconstruct your knowledge graph at any point in the past without modifying the current graph.
- Parse natural-language temporal queries and rewrite them into structured datetime constraints.
- Reason over time intervals using a full deterministic Allen algebra implementation.
- Normalize any date expression β ISO 8601, relative phrases, domain-specific vocabulary β into UTC.
- Extract temporal validity from text using the LLM, with calibrated confidence scores.
β [Temporal docs](docs/reference/) Β· [Temporal cookbook](cookbook/)
### πΊοΈ Knowledge Graphs
Build, enrich, and analyze knowledge graphs with production-grade algorithms.
- Add entities, relationships, and typed properties with full metadata support.
- Run PageRank, betweenness centrality, and Louvain community detection out of the box.
- Generate Node2Vec embeddings and score potential new links.
- Delta processing keeps large graphs fresh without full recomputes.
β [KG docs](docs/reference/)
### π Semantic Extraction
Pull structured knowledge out of raw text.
- Extract entities and relationships from text using LLMs or rule-based methods.
- Generate (subject, predicate, object) triplets ready to load into any KG.
- Deduplicate entities intelligently β Jaro-Winkler, semantic, and hybrid strategies. v2 is up to **6.98x faster**.
- Optionally have the LLM annotate each relation with temporal validity and confidence.
β [Extraction docs](docs/reference/)
### π§ Reasoning Engines
Go beyond retrieval β derive new facts from what you know.
- **Forward chaining** β IF/THEN rules over facts.
- **Rete network** β high-throughput production rule matching for real-time event streams.
- **Deductive** β classical inference from axioms.
- **Abductive** β generate plausible hypotheses from observations.
- **SPARQL** β query-based inference over RDF graphs.
- **Temporal** β deterministic Allen algebra, no LLM required.
β [Reasoning docs](docs/reference/)
### π Provenance & Auditability
Every fact, decision, and computation links back to where it came from.
- Auto-stamp transaction time on every provenance record.
- Query full revision history for any fact β version, author, validity window, supersession chain.
- Export audit logs in JSON or CSV.
- Export temporal relationships as OWL-Time RDF triples.
- W3C PROV-O compliant across all modules.
β [Provenance docs](docs/reference/)
### π· Ontology & SHACL
Build, import, and enforce data contracts for your knowledge graphs.
- Auto-generate OWL ontologies from any KG β no hand-authoring.
- Import existing ontologies in OWL, RDF, Turtle, or JSON-LD.
- Derive SHACL shapes from any ontology and validate graphs against them.
- Manage SKOS controlled vocabularies with hierarchy, search, and REST APIs.
β [Ontology docs](docs/reference/ontology.md)
### π Pipeline & Production
Orchestrate multi-stage KG pipelines with reliability built in.
- Chain ingest β extract β deduplicate β build β export stages with a fluent builder API.
- Validate the pipeline config before running it.
- Retry failed stages with exponential backoff, fixed delay, or linear backoff.
- 100+ LLM providers via LiteLLM β OpenAI, Anthropic, Mistral, Ollama, Azure, Bedrock, and more.
β [Pipeline docs](docs/reference/)
### π Vector Store
Semantic memory with hybrid search and metadata filtering.
- FAISS, Pinecone, Weaviate, Qdrant, Milvus, PgVector, and in-memory β one API for all.
- Hybrid search mixes vector similarity and keyword matching with configurable weights.
- Filter by any metadata field, or tune similarity weights per use case.
---
## Modules
| Module | What it provides |
|---|---|
| `semantica.context` | Context graphs, agent memory, decision tracking, causal analysis, precedent search, policy engine |
| `semantica.kg` | Knowledge graph construction, graph algorithms, centrality, community detection, embeddings, link prediction, provenance |
| `semantica.semantic_extract` | NER, relation extraction, event extraction, coreference, triplet generation, LLM-enhanced extraction |
| `semantica.reasoning` | Forward chaining, Rete network, deductive, abductive, SPARQL reasoning, explanation generation |
| `semantica.vector_store` | FAISS, Pinecone, Weaviate, Qdrant, Milvus, PgVector, in-memory; hybrid & filtered search |
| `semantica.export` | RDF (Turtle/JSON-LD/N-Triples/XML), Parquet, ArangoDB AQL, CSV, YAML, OWL, graph formats |
| `semantica.ingest` | Files (PDF, DOCX, CSV, HTML), web crawl, feeds, databases, Snowflake, MCP, email, repositories |
| `semantica.ontology` | Auto-generation (6-stage pipeline), OWL/RDF export, import (OWL/RDF/Turtle/JSON-LD), validation, versioning, **SHACL shape generation & validation** |
| `semantica.pipeline` | Pipeline DSL, parallel workers, validation, retry policies, failure handling, resource scheduling |
| `semantica.graph_store` | Graph database backends β Neo4j, FalkorDB, Apache AGE, Amazon Neptune; Cypher queries |
| `semantica.embeddings` | Text embedding generation β Sentence-Transformers, FastEmbed, OpenAI, BGE; similarity calculation |
| `semantica.deduplication` | Entity deduplication, similarity scoring, merging, clustering; blocking and semantic strategies |
| `semantica.provenance` | W3C PROV-O compliant end-to-end lineage tracking, source attribution, audit trails |
| `semantica.parse` | Document parsing β PDF, DOCX, PPTX, HTML, code, email, structured data, media with OCR |
| `semantica.split` | Document chunking β recursive, semantic, entity-aware, relation-aware, graph-based, ontology-aware |
| `semantica.normalize` | Data normalization for text, entities, dates, numbers, quantities, languages, encodings |
| `semantica.conflicts` | Multi-source conflict detection (value, type, relationship, temporal, logical) with resolution strategies |
| `semantica.change_management` | Version storage, change tracking, checksums, audit trails, compliance support for KGs and ontologies |
| `semantica.triplet_store` | RDF triplet store integration β Blazegraph, Jena, RDF4J; SPARQL queries and bulk loading |
| `semantica.visualization` | Interactive and static visualization of KGs, ontologies, embeddings, analytics, and temporal graphs |
| `semantica.seed` | Seed data management for initial KG construction from CSV, JSON, databases, and APIs |
| `semantica.core` | Framework orchestration, configuration management, knowledge base construction, plugin system |
| `semantica.llms` | LLM provider integrations β Groq, OpenAI, Novita AI, HuggingFace, LiteLLM |
| `semantica.utils` | Shared utilities β logging, validation, exception handling, constants, types, progress tracking |
## π» Code Examples
### Decision Tracking
```python
from semantica.context import ContextGraph
graph = ContextGraph(advanced_analytics=True)
# Record decisions with full reasoning context
# record_decision() accepts keyword args and returns the decision ID
loan_id = graph.record_decision(
category="loan_approval",
scenario="Mortgage β 780 credit score, 28% DTI",
reasoning="Strong credit history, stable 8-year income, low DTI",
outcome="approved",
confidence=0.95,
)
rate_id = graph.record_decision(
category="interest_rate",
scenario="Set rate for approved mortgage",
reasoning="Prime applicant qualifies for lowest tier",
outcome="rate_set_6.2pct",
confidence=0.98,
)
# Link decisions causally β builds an auditable chain
graph.add_causal_relationship(loan_id, rate_id, relationship_type="enables")
# Query the graph
similar = graph.find_similar_decisions("mortgage approval", max_results=5)
chain = graph.trace_decision_chain(loan_id)
impact = graph.analyze_decision_impact(loan_id)
compliance = graph.check_decision_rules({"category": "loan_approval", "confidence": 0.95})
```
β [Full decision tracking guide](docs/reference/) Β· [Cookbook examples](cookbook/)
### Temporal GraphRAG
```python
from semantica.kg import TemporalQueryRewriter, TemporalNormalizer
from semantica.context import TemporalGraphRetriever
from datetime import datetime, timezone
# Parse temporal intent from natural language β zero LLM calls
rewriter = TemporalQueryRewriter()
result = rewriter.rewrite("What decisions were made before the 2024 merger?")
# result.temporal_intent β "before"
# result.at_time β datetime(2024, ..., tzinfo=UTC)
# result.rewritten_query β "What decisions were made"
# Filter any retriever to a point in time β drop-in wrapper
retriever = TemporalGraphRetriever(
base_retriever=your_retriever,
at_time=datetime(2024, 3, 1, tzinfo=timezone.utc),
)
ctx = retriever.retrieve("supplier approval decisions")
# Normalize any date expression to UTC β zero LLM calls
normalizer = TemporalNormalizer()
start, end = normalizer.normalize("Q1 2024")
# β (datetime(2024, 1, 1, UTC), datetime(2024, 3, 31, UTC))
start, end = normalizer.normalize("effective from 2023-09-01")
# β (datetime(2023, 9, 1, UTC), None)
```
β [Temporal GraphRAG docs](docs/reference/) Β· [Temporal cookbook](cookbook/)
### Point-in-Time Graph Snapshots
```python
from semantica.context import ContextGraph, AgentContext
from semantica.vector_store import VectorStore
from datetime import datetime, timezone
graph = ContextGraph()
# record_decision() accepts keyword args and supports validity windows
graph.record_decision(
category="policy",
scenario="Approve supplier A",
outcome="approved",
confidence=0.9,
valid_from=datetime(2024, 1, 1, tzinfo=timezone.utc),
valid_until=datetime(2024, 6, 30, tzinfo=timezone.utc),
)
# Reconstruct the graph exactly as it was on any date
# The source graph is never mutated
snapshot = graph.state_at(datetime(2024, 3, 15, tzinfo=timezone.utc))
# Named checkpoints β checkpoint() and diff_checkpoints() live on AgentContext
context = AgentContext(
vector_store=VectorStore(backend="inmemory"),
knowledge_graph=graph,
decision_tracking=True,
)
context.checkpoint("before_merge")
# ... make changes ...
diff = context.diff_checkpoints("before_merge", "after_merge")
# β {"decisions_added": [...], "relationships_added": [...], ...}
```
### Semantic Extraction
```python
from semantica.semantic_extract import NERExtractor, RelationExtractor, TripletExtractor
text = """
OpenAI released GPT-4 in March 2023. Microsoft integrated GPT-4 into Azure.
Anthropic, founded by former OpenAI researchers, released Claude as a competing model.
"""
# Step 1 β extract entities
entities = NERExtractor().extract_entities(text)
# β [Entity(label="OpenAI", ...), Entity(label="GPT-4", ...), ...]
# Step 2 β extract relations (requires entities)
relations = RelationExtractor().extract_relations(text, entities=entities)
# β [Relation(source="OpenAI", type="released", target="GPT-4"), ...]
# Step 3 β extract full (subject, predicate, object) triplets
triplets = TripletExtractor().extract_triplets(text)
```
### Semantic Extraction with Temporal Bounds
```python
from semantica.semantic_extract import NERExtractor
from semantica.semantic_extract.methods import extract_relations_llm
text = "The partnership was effective from January 2022 until the merger in Q3 2024."
# extract_relations_llm requires pre-extracted entities as second arg
entities = NERExtractor().extract_entities(text)
relations = extract_relations_llm(
text,
entities,
provider="openai",
extract_temporal_bounds=True, # LLM annotates each relation with validity window
)
for rel in relations:
print(f"{rel.source} β {rel.target}")
print(f" valid: {rel.metadata['valid_from']} β {rel.metadata['valid_until']}")
print(f" confidence: {rel.metadata['temporal_confidence']}")
```
β [Extraction docs](docs/reference/)
### Knowledge Graphs & Algorithms
```python
from semantica.kg import GraphBuilder, CentralityCalculator, NodeEmbedder, LinkPredictor
# Build a KG from entity/relationship dicts
builder = GraphBuilder()
graph = builder.build({
"entities": [
{"id": "bert", "label": "BERT", "type": "Model"},
{"id": "transformer", "label": "Transformer", "type": "Architecture"},
{"id": "gpt4", "label": "GPT-4", "type": "Model"},
],
"relationships": [
{"source": "bert", "target": "transformer", "type": "based_on"},
{"source": "gpt4", "target": "transformer", "type": "based_on"},
],
})
# Graph algorithms
centrality = CentralityCalculator().calculate_pagerank(graph)
embeddings = NodeEmbedder().compute_embeddings(
graph, node_labels=["Model"], relationship_types=["based_on"]
)
link_score = LinkPredictor().score_link(graph, "gpt4", "bert", method="common_neighbors")
```
β [KG algorithm docs](docs/reference/) Β· [KG cookbook](cookbook/)
### Reasoning
```python
from semantica.reasoning import Reasoner, ReteEngine
# Forward chaining β derive new facts from rules
reasoner = Reasoner()
reasoner.add_rule("IF Person(?x) THEN Mortal(?x)")
results = reasoner.infer_facts(["Person(Socrates)"])
# β ["Mortal(Socrates)"]
# Rete network β build a rule network, add facts, then run pattern matching
from semantica.reasoning import Rule, Fact, RuleType
rete = ReteEngine()
rule = Rule(
rule_id="r1",
name="flag_high_risk",
conditions=[
{"field": "amount", "operator": ">", "value": 10000},
{"field": "country", "operator": "in", "value": ["IR", "KP", "SY"]},
],
conclusion="flag_for_compliance_review",
rule_type=RuleType.IMPLICATION,
)
rete.build_network([rule])
fact = Fact(fact_id="f1", predicate="transaction", arguments=[{"amount": 15000, "country": "IR"}])
rete.add_fact(fact)
matches = rete.match_patterns() # returns List[Match]
```
β [Reasoning docs](docs/reference/)
### Ontology Generation & Validation
```python
from semantica.ontology import OntologyEngine
engine = OntologyEngine()
# Derive an OWL ontology from any data dict
ontology = engine.from_data(your_data_dict)
# Export as OWL (Turtle or RDF/XML)
engine.export_owl(ontology, path="domain_ontology.owl", format="turtle")
# Validate ontology consistency
result = engine.validate(ontology)
# Generate ontology from raw text using an LLM
ontology = engine.from_text("Employees work at companies. Companies have departments.")
# Convert ontology to OWL string
owl_str = engine.to_owl(ontology, format="turtle")
```
β [Ontology docs](docs/reference/ontology.md)
### Pipeline Orchestration
```python
from semantica.pipeline import PipelineBuilder, PipelineValidator
from semantica.pipeline import RetryPolicy, RetryStrategy
# Build a multi-stage pipeline using add_step(name, type, **config)
builder = (
PipelineBuilder()
.add_step("ingest", "file_ingest", source="./documents/", recursive=True)
.add_step("extract", "triplet_extract")
.add_step("deduplicate", "entity_dedup", threshold=0.85)
.add_step("build_kg", "kg_build")
.add_step("export", "rdf_export", format="turtle", output="output/kg.ttl")
.set_parallelism(4) # set_parallelism(), not with_parallel_workers()
)
pipeline = builder.build(name="kg_pipeline")
# Validate before running β catches config errors early
result = PipelineValidator().validate(pipeline)
if result.valid:
pipeline.run()
```
β [Pipeline docs](docs/reference/)
---
## π¦ Modules
- **`semantica.context`** β context graphs, decisions, causal chains, precedent search, policy engine, checkpoints
- **`semantica.kg`** β KG construction, graph algorithms, embeddings, link prediction, temporal query engine, Allen algebra, `TemporalNormalizer`, provenance
- **`semantica.semantic_extract`** β NER, relation extraction, triplet generation, LLM extraction with temporal bounds, deduplication
- **`semantica.reasoning`** β forward chaining, Rete, deductive, abductive, SPARQL, temporal algebra
- **`semantica.vector_store`** β FAISS, Pinecone, Weaviate, Qdrant, Milvus, PgVector, in-memory; hybrid & filtered search
- **`semantica.export`** β RDF (Turtle/JSON-LD/N-Triples/XML), OWL-Time, Parquet, ArangoDB AQL, OWL, SHACL
- **`semantica.ingest`** β files, web crawl, databases, Snowflake, email, repositories
- **`semantica.ontology`** β OWL generation & import, SHACL generation & validation, SKOS vocabulary management
- **`semantica.pipeline`** β stage chaining, parallel workers, validation, retry policies, failure handling
- **`semantica.graph_store`** β Neo4j, FalkorDB, Apache AGE, Amazon Neptune; Cypher queries
- **`semantica.embeddings`** β Sentence-Transformers, FastEmbed, OpenAI, BGE; similarity
- **`semantica.deduplication`** β entity dedup, similarity scoring, blocking and semantic strategies
- **`semantica.provenance`** β W3C PROV-O lineage, revision history, audit log export
- **`semantica.parse`** β PDF, DOCX, PPTX, HTML, code, email, media with OCR
- **`semantica.split`** β recursive, semantic, entity-aware, graph-based, ontology-aware chunking
- **`semantica.conflicts`** β multi-source conflict detection with resolution strategies
- **`semantica.change_management`** β version storage, checksums, audit trails, compliance support
- **`semantica.triplet_store`** β Blazegraph, Jena, RDF4J; SPARQL, bulk loading, SKOS helpers
- **`semantica.visualization`** β KG, ontology, embedding, and temporal graph visualization
- **`semantica.llms`** β Groq, OpenAI, Novita AI, HuggingFace, LiteLLM
---
## π Integrations
### Graph Databases
- **AWS Neptune** β Amazon Neptune with IAM authentication
- **Apache AGE** β PostgreSQL + openCypher via SQL
- **FalkorDB** β native support for decision queries and causal analysis
### Vector Databases
- **FAISS** β built-in, zero extra dependencies
- **Pinecone** β `pip install semantica[vectorstore-pinecone]`
- **Weaviate** β `pip install semantica[vectorstore-weaviate]`
- **Qdrant** β `pip install semantica[vectorstore-qdrant]`
- **Milvus** β `pip install semantica[vectorstore-milvus]`
- **PgVector** β `pip install semantica[vectorstore-pgvector]`
### Data Sources
- **Files** β PDF, DOCX, HTML, JSON, CSV, Excel, PPTX, archives
- **Web** β configurable-depth crawler
- **Databases** β SQL via `DBIngestor`
- **Snowflake** β table/query ingestion, pagination, password/key-pair/OAuth/SSO auth Β· `pip install semantica[db-snowflake]`
- **Docling** β advanced table and layout extraction (PDF, DOCX, PPTX, XLSX)
### LLM Providers
- **LiteLLM** β 100+ models: OpenAI, Anthropic, Cohere, Mistral, Ollama, Azure, AWS Bedrock, and more
- **Novita AI** β OpenAI-compatible (`deepseek/deepseek-v3.2` and more) Β· set `NOVITA_API_KEY`
### Agentic Frameworks
Semantica complements β not replaces β LangChain, LlamaIndex, AutoGen, CrewAI, Google ADK, and more.
> **Agno β First-Class Integration** Β· `pip install semantica[agno]`
>
> Five ready-to-use Agno components:
> - `AgnoContextStore` β graph-backed agent memory
> - `AgnoKnowledgeGraph` β multi-hop GraphRAG knowledge base
> - `AgnoDecisionKit` β 6 decision-intelligence tools
> - `AgnoKGToolkit` β 7 KG pipeline tools
> - `AgnoSharedContext` β shared context graph for multi-agent teams
---
## π οΈ Installation
```bash
# Core
pip install semantica
# All optional dependencies
pip install semantica[all]
# Pick only what you need
pip install semantica[vectorstore-pinecone]
pip install semantica[vectorstore-weaviate]
pip install semantica[vectorstore-qdrant]
pip install semantica[vectorstore-milvus]
pip install semantica[vectorstore-pgvector]
pip install semantica[db-snowflake] # Snowflake ingestion
pip install semantica[agno] # Agno integration
# From source
git clone https://github.com/Hawksight-AI/semantica.git
cd semantica
pip install -e ".[dev]"
pytest tests/
```
---
## π Built for High-Stakes Domains
> Every answer explainable. Every decision auditable. Every fact traceable.
- π₯ **Healthcare** β clinical decision support, drug interaction graphs, patient safety audit trails
- π° **Finance** β fraud detection, regulatory compliance, risk knowledge graphs
- βοΈ **Legal** β evidence-backed research, contract analysis, case law reasoning
- π **Cybersecurity** β threat attribution, incident response timelines, provenance tracking
- ποΈ **Government** β policy decision records, classified information governance
- π **Infrastructure** β power grids, transportation networks, operational decision logs
- π€ **Autonomous Systems** β decision logs, safety validation, explainable AI
---
## π€ Community & Support
- π¬ **[Discord](https://discord.gg/sV34vps5hH)** β real-time help and showcases
- π‘ **[GitHub Discussions](https://github.com/Hawksight-AI/semantica/discussions)** β Q&A and feature requests
- π **[GitHub Issues](https://github.com/Hawksight-AI/semantica/issues)** β bug reports
- π **[Documentation](https://github.com/Hawksight-AI/semantica/tree/main/docs)** β full reference docs
- π³ **[Cookbook](https://github.com/Hawksight-AI/semantica/tree/main/cookbook)** β runnable notebooks and recipes
- π **[Changelog](CHANGELOG.md)** β what changed and why
- π **[Release Notes](RELEASE_NOTES.md)** β per-contributor breakdown
---
## π€ Contributing
All contributions welcome β bug fixes, features, tests, and docs.
1. Fork the repo and create a branch
2. `pip install -e ".[dev]"`
3. Write tests alongside your changes
4. Open a PR and tag `@KaifAhmad1` for review
See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
---
MIT License Β· Built by [Hawksight AI](https://github.com/Hawksight-AI) Β· [β Star on GitHub](https://github.com/Hawksight-AI/semantica)
[GitHub](https://github.com/Hawksight-AI/semantica) Β· [Discord](https://discord.gg/sV34vps5hH) Β· [X / Twitter](https://x.com/BuildSemantica)