🧠 Semantica

A Framework for Building Context Graphs and Decision Intelligence Layers for AI

⭐ 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.

Get Started View on GitHub

The Problem¶

AI agents today are capable but not trustworthy:

• No memory structure — agents store embeddings, not meaning. Retrieval is fuzzy; there's no way to ask why something was recalled.
• No decision trail — agents make decisions continuously but record nothing. When something goes wrong, there's no history to debug or audit.
• No provenance — outputs cannot be traced back to source facts. In regulated industries, this is a compliance blocker.
• No reasoning transparency — black-box answers with no explanation of how a conclusion was reached.
• No conflict detection — contradictory facts silently coexist in vector stores, producing unpredictable answers.

These aren't edge cases. They are the reason AI cannot be deployed in healthcare, finance, legal, and government without custom guardrails built from scratch.

The Solution¶

Semantica is the context and intelligence layer you add to your AI stack:

• Context Graphs — structured graph of entities, relationships, and decisions your agent builds as it works. Queryable, traceable, persistent.
• Decision Intelligence — every decision is a first-class object: recorded, linked causally, searchable by precedent, and analyzable for downstream impact.
• Provenance — every fact links to its source. W3C PROV-O compliant. Full lineage from ingestion to inference.
• Reasoning engines — forward chaining, Rete networks, deductive, abductive, and SPARQL reasoning. Explainable inference paths, not black-box answers.
• Deduplication & QA — conflict detection, entity resolution, and validation built into the pipeline.

Works alongside LangChain, LlamaIndex, AutoGen, CrewAI, and any LLM provider — Semantica is not a replacement, it's the accountability layer on top.

⚡ Quick Installation¶

pip install semantica

from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

context = AgentContext(
    vector_store=VectorStore(backend="inmemory"),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
)

# Store a memory
context.store("GPT-4 outperforms GPT-3.5 on reasoning benchmarks by 40%")

# Record a decision
decision_id = context.record_decision(
    category="model_selection",
    scenario="Choose LLM for production reasoning pipeline",
    reasoning="GPT-4 benchmark advantage justifies 3x cost increase",
    outcome="selected_gpt4",
    confidence=0.91,
)

# Find similar past decisions and analyze downstream impact
precedents = context.find_precedents("model selection reasoning", limit=5)
influence  = context.analyze_decision_influence(decision_id)

Full Quick Start  •  Cookbook  •  Join Discord

What's New in v0.3.0¶

First stable release (Production/Stable on PyPI).

Core Value Proposition¶

Features¶

Context & Decision Intelligence¶

• Context Graphs — structured, persistent graph of entities, relationships, and decisions
• Decision tracking — add_decision(), record_decision() for full lifecycle management
• Causal chains — add_causal_relationship(), trace_decision_chain()
• Precedent search — hybrid similarity search over past decisions via find_similar_decisions()
• Influence analysis — analyze_decision_impact(), analyze_decision_influence()
• Policy engine — check_decision_rules() with versioned, automated compliance rules
• Agent memory — AgentMemory with short/long-term storage and conversation history

Knowledge Graphs¶

• Graph construction — entities, relationships, properties, typed edges
• Algorithms — PageRank, betweenness centrality, clustering coefficient, community detection
• Node embeddings — Node2Vec via NodeEmbedder; cosine similarity via SimilarityCalculator
• Link prediction — score potential edges via LinkPredictor
• Temporal graphs — time-aware nodes and edges with validity windows
• Delta processing — incremental updates without full recompute

Semantic Extraction¶

• NER — named entity recognition, normalization, classification
• Relation extraction — triplet generation via LLMs or rule-based methods, with "llm_typed" metadata
• Deduplication v1/v2 — Jaro-Winkler, blocking_v2, hybrid_v2, semantic_v2; dedup_triplets() for triples

Reasoning¶

• Forward chaining — Reasoner with IF/THEN string rules and dict facts
• Rete network — ReteEngine for high-throughput production rule matching
• Deductive / Abductive — DeductiveReasoner, AbductiveReasoner
• SPARQL — SPARQLReasoner for query-based inference over RDF graphs

Provenance & Auditability¶

• Entity provenance — ProvenanceTracker.track_entity()
• Algorithm provenance — AlgorithmTrackerWithProvenance
• 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
• Search modes — semantic top-k, hybrid (vector + keyword), metadata-filtered

Data Ingestion¶

• Files — PDF, DOCX, HTML, JSON, CSV, Excel, PPTX, archives
• Sources — web crawl, SQL databases, Snowflake, feeds, email, repositories
• Docling — advanced parsing with table and layout extraction
• Media — image OCR, audio/video metadata

Export¶

• RDF — Turtle, JSON-LD, N-Triples, XML via RDFExporter
• Parquet — ParquetExporter for Spark/BigQuery/Databricks pipelines
• ArangoDB AQL — ready-to-run INSERT statements
• OWL ontologies — Turtle or RDF/XML

Pipeline & Ontology¶

• Pipeline DSL — PipelineBuilder with stage chaining, parallel workers, retry policies
• Ontology — auto-generate OWL from KGs, import OWL/RDF/Turtle/JSON-LD, HermiT/Pellet validation

Modules¶

Built for High-Stakes Domains¶

Where every decision must be accountable and mistakes have real consequences:

• 🏥 Healthcare & Life Sciences — Clinical decision support, drug interactions, patient safety
• 💰 Finance & Risk — Fraud detection, SOX/GDPR/MiFID II compliance, risk assessment
• ⚖️ Legal & Compliance — Evidence-backed research, contract analysis, regulatory tracking
• 🔒 Cybersecurity — Threat attribution, incident response, security audit trails
• 🏛️ Government & Defense — Policy decisions, classified information handling, defense intelligence
• 🏭 Critical Infrastructure — Power grids, transportation safety, emergency response
• 🚗 Autonomous Systems — Self-driving, robotics safety, industrial automation

Choose Your Path¶

Installation¶

pip install semantica

# With all optional dependencies
pip install semantica[all]

git clone https://github.com/Hawksight-AI/semantica.git
cd semantica
pip install -e .          # core
pip install -e ".[all]"   # all extras

git clone https://github.com/Hawksight-AI/semantica.git
cd semantica
pip install -e ".[dev]"

docker pull semantica/semantica:latest
docker run -it semantica/semantica

Why Semantica?¶

Learn More¶

• Getting Started — your first knowledge graph in 5 minutes
• Core Concepts — knowledge graphs, ontologies, and semantic reasoning
• Cookbook — 14 domain-specific cookbooks with Jupyter notebooks
• API Reference — complete technical documentation