semantica/docs/getting-started.md

title, description, icon

title	description	icon
Getting Started	The context and intelligence layer for AI — turning raw data into explainable, auditable knowledge graphs.	rocket

Just here for code? Jump straight to the [Quickstart Tutorial](quickstart) or explore the [Cookbook](cookbook) for interactive notebooks.

---

What You Can Build

Enhanced retrieval with semantic graph reasoning — ground LLM responses in traceable, structured knowledge. Agents with structured decision history, causal chains, and precedent search. Every choice is recorded and auditable. Build, validate, and maintain enterprise-grade semantic knowledge bases from multi-source data. W3C PROV-O provenance on every fact. HIPAA, SOX, GDPR, FDA 21 CFR Part 11 infrastructure built in.

---

Installation

pip install semantica

With all optional dependencies:

pip install semantica[all]

Verify:

import semantica
print(semantica.__version__)

---

Quick Start

from semantica.ingest import FileIngestor
from semantica.parse import DocumentParser
from semantica.semantic_extract import NERExtractor, RelationExtractor
from semantica.kg import GraphBuilder

# Ingest → Parse → Extract → Build
ingestor = FileIngestor()
sources = ingestor.ingest("data/sample.pdf")

parser = DocumentParser()
parsed = parser.parse(sources[0])

ner = NERExtractor()
entities = ner.extract(parsed)

rel = RelationExtractor()
relationships = rel.extract(parsed, entities=entities)

graph = GraphBuilder(merge_entities=True).build(
    entities=entities, relationships=relationships
)
print(f"{len(graph.nodes)} nodes, {len(graph.edges)} edges")

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

context = AgentContext(
    vector_store=VectorStore(backend="faiss", dimension=768),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
)

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

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

# Find similar past decisions
precedents = context.find_precedents("model selection", limit=5)

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

context = AgentContext(
    vector_store=VectorStore(backend="faiss", dimension=768),
    knowledge_graph=ContextGraph(advanced_analytics=True),
)

# Load your knowledge graph
context.load_graph("company_kg.json")

# Multi-hop GraphRAG query
result = context.query(
    "What companies were founded by people who worked at Apple?",
    mode="graphrag",
    reasoning=True,
)

# Every claim links back to a source node
for claim in result.claims:
    print(f"{claim.text}  →  source: {claim.source_node}")

---

Core Architecture

Semantica uses a modular, layered architecture — import only what you need.

Layer	Modules	Purpose
Input	ingest, parse, split, normalize	Load and prepare data
Semantic	semantic_extract, kg, ontology, reasoning	Extract meaning
Storage	embeddings, vector_store, graph_store	Persist knowledge
Quality	deduplication, conflicts	Validate and clean
Context	context, provenance, change_management	Track decisions and lineage
Output	export, visualization, pipeline	Deliver results

---

Next Steps

Knowledge graphs, ontologies, and reasoning explained in depth. Full 6-step pipeline with `` walkthrough. 40+ domain-specific Jupyter notebook tutorials. Complete module documentation for every class and method.

---

Help

Ask questions, share projects, get community support. Report bugs or request features. Common questions answered.