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

Already installed? Jump straight to [Quickstart](quickstart). Need setup help first? See [Installation](installation).

What You Can Build

Ground LLM responses in traceable, structured knowledge. Every claim links back to a source node. 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]

For virtual environments and platform-specific setup, see the full Installation guide.

Verify:

import semantica
print(semantica.__version__)  # 0.5.0

Quick Start

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

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 fact 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),
)

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, triplet_store	Persist knowledge
Quality	deduplication, conflicts	Validate and clean
Context	context, provenance, change_management	Track decisions and lineage
Output	export, visualization, pipeline, explorer	Deliver results

Next Steps

Knowledge graphs, ontologies, and reasoning explained in depth. Full 6-step pipeline walkthrough with working code. Every module, class, and common chain explained. Complete module documentation for every class and method.

Help

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