mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-09-10 04:00:35 +00:00
Mohd Kaif
a326c7d3bd
* fix: replace invalid Mintlify theme 'venus' with 'mint' * docs: replace em dashes with colons across all docs files * fix: strip UTF-8 BOM from all docs files (broke frontmatter detection)
284 lines
9.2 KiB
Markdown
284 lines
9.2 KiB
Markdown
---
|
|
title: "Getting Started"
|
|
description: "The context and intelligence layer for AI: turning raw data into explainable, auditable knowledge graphs."
|
|
icon: "rocket"
|
|
---
|
|
|
|
<Tip>
|
|
Already installed? Jump straight to [Quickstart](quickstart). Need setup help first? See [Installation](installation).
|
|
</Tip>
|
|
|
|
## What You Can Build
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="GraphRAG Systems" icon="diagram-project">
|
|
Ground LLM responses in traceable, structured knowledge. Every claim links back to a source node.
|
|
</Card>
|
|
<Card title="Accountable AI Agents" icon="robot">
|
|
Agents with structured decision history, causal chains, and precedent search. Every choice is recorded and auditable.
|
|
</Card>
|
|
<Card title="Production Knowledge Graphs" icon="sitemap">
|
|
Build, validate, and maintain enterprise-grade semantic knowledge bases from multi-source data.
|
|
</Card>
|
|
<Card title="Compliance-Ready AI" icon="shield-check">
|
|
W3C PROV-O provenance on every fact. HIPAA, SOX, GDPR, FDA 21 CFR Part 11 infrastructure built in.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
|
|
## Setup in 3 Steps
|
|
|
|
<Steps>
|
|
<Step title="Install Semantica">
|
|
<CodeGroup>
|
|
|
|
```bash pip (recommended)
|
|
pip install semantica
|
|
```
|
|
|
|
```bash With all extras
|
|
pip install semantica[all]
|
|
```
|
|
|
|
```bash From source
|
|
git clone https://github.com/semantica-agi/semantica.git
|
|
cd semantica
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
<Check>
|
|
Verify installation:
|
|
```python
|
|
import semantica
|
|
print(semantica.__version__) # 0.5.0
|
|
```
|
|
</Check>
|
|
</Step>
|
|
|
|
<Step title="Choose your path">
|
|
Pick the track that matches what you're building: each starts with a focused 5-minute example.
|
|
|
|
| Track | You want to... | Start with |
|
|
| :----- | :-------------- | :--------- |
|
|
| **Knowledge Graph** | Turn documents into structured, queryable graphs | [Quickstart → Step 1](quickstart) |
|
|
| **Agent Context** | Give your AI agent persistent memory and decision tracking | [Context reference](reference/context) |
|
|
| **GraphRAG** | Ground LLM answers in structured knowledge | [Concepts → GraphRAG](concepts#graphrag) |
|
|
| **MCP Integration** | Use Semantica from Claude Desktop or VS Code | [MCP Server](reference/mcp_server) |
|
|
|
|
</Step>
|
|
|
|
<Step title="Run the pipeline">
|
|
The full 6-step pipeline: ingest, parse, extract, build, visualize, export: is in the [Quickstart](quickstart). Takes under 5 minutes with pattern-based extraction (no API key required).
|
|
|
|
<Note>
|
|
An LLM API key is **optional** for the quickstart. Pattern-based extraction works out of the box: upgrade to LLM extraction for higher accuracy when you're ready.
|
|
</Note>
|
|
</Step>
|
|
</Steps>
|
|
|
|
|
|
## Choose Your Path
|
|
|
|
<Tabs>
|
|
<Tab title="Knowledge Graph">
|
|
Build a structured knowledge graph from any document or data source.
|
|
|
|
```python
|
|
from semantica.ingest import FileIngestor
|
|
from semantica.parse import DocumentParser
|
|
from semantica.semantic_extract import NERExtractor, RelationExtractor
|
|
from semantica.kg import GraphBuilder
|
|
|
|
# 1. Ingest
|
|
sources = FileIngestor().ingest("data/report.pdf")
|
|
|
|
# 2. Parse
|
|
parsed = DocumentParser().parse(sources[0])
|
|
|
|
# 3. Extract
|
|
ner = NERExtractor(method="pattern") # no API key needed
|
|
entities = ner.extract(parsed)
|
|
relationships = RelationExtractor().extract(parsed, entities=entities)
|
|
|
|
# 4. Build
|
|
graph = GraphBuilder(merge_entities=True).build(
|
|
entities=entities, relationships=relationships
|
|
)
|
|
print(f"{len(graph['nodes'])} nodes, {len(graph['relationships'])} edges")
|
|
```
|
|
|
|
**Next:** [Full pipeline walkthrough →](quickstart)
|
|
</Tab>
|
|
|
|
<Tab title="Agent Context">
|
|
Give your agent persistent memory, decision tracking, and precedent search.
|
|
|
|
```python
|
|
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 by 40%")
|
|
|
|
# Record a decision with full causal chain
|
|
decision_id = context.record_decision(
|
|
category="model_selection",
|
|
scenario="Choose LLM for production pipeline",
|
|
reasoning="GPT-4 benchmark advantage justifies cost",
|
|
outcome="selected_gpt4",
|
|
confidence=0.91,
|
|
)
|
|
|
|
# Search past decisions before making a new one
|
|
precedents = context.find_precedents("model selection", limit=5)
|
|
```
|
|
|
|
**Next:** [Context module reference →](reference/context)
|
|
</Tab>
|
|
|
|
<Tab title="GraphRAG">
|
|
Ground every LLM response in your knowledge graph: no floating assertions.
|
|
|
|
```python
|
|
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),
|
|
)
|
|
|
|
# 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}")
|
|
```
|
|
|
|
**Next:** [GraphRAG concepts →](concepts#graphrag)
|
|
</Tab>
|
|
|
|
<Tab title="MCP Integration">
|
|
Use Semantica from Claude Desktop, VS Code, Cursor, or any MCP client: no Python code required after setup.
|
|
|
|
```bash
|
|
pip install semantica
|
|
```
|
|
|
|
Add to your MCP client config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"semantica": {
|
|
"command": "semantica-mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
12 tools available instantly: extract entities, query graph, record decisions, run reasoning, export results.
|
|
|
|
**Next:** [MCP Server reference →](reference/mcp_server)
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
|
|
## Core Architecture
|
|
|
|
Semantica uses a modular, layered architecture: import only what you need.
|
|
|
|
<CardGroup cols={3}>
|
|
<Card title="Input Layer" icon="database" href="reference/ingest">
|
|
Load and prepare data from any source.
|
|
**Modules:** `ingest`, `parse`, `split`, `normalize`
|
|
</Card>
|
|
<Card title="Semantic Layer" icon="microchip" href="reference/semantic_extract">
|
|
Extract meaning from raw text.
|
|
**Modules:** `semantic_extract`, `kg`, `ontology`, `reasoning`
|
|
</Card>
|
|
<Card title="Storage Layer" icon="hard-drive" href="reference/vector_store">
|
|
Persist knowledge for retrieval.
|
|
**Modules:** `embeddings`, `vector_store`, `graph_store`, `triplet_store`
|
|
</Card>
|
|
<Card title="Quality Layer" icon="check-circle" href="reference/deduplication">
|
|
Validate and deduplicate.
|
|
**Modules:** `deduplication`, `conflicts`
|
|
</Card>
|
|
<Card title="Context Layer" icon="brain" href="reference/context">
|
|
Track decisions and lineage.
|
|
**Modules:** `context`, `provenance`, `change_management`
|
|
</Card>
|
|
<Card title="Output Layer" icon="share-nodes" href="reference/export">
|
|
Deliver results downstream.
|
|
**Modules:** `export`, `visualization`, `pipeline`, `explorer`
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
|
|
## "Which module do I need?" Quick Reference
|
|
|
|
| I want to... | Module | Key class |
|
|
| :------------ | :------ | :--------- |
|
|
| Load a PDF / web page / database | `ingest` | `FileIngestor`, `WebIngestor` |
|
|
| Extract text and tables from a PDF | `parse` | `DocumentParser`, `DoclingParser` |
|
|
| Find entities in text | `semantic_extract` | `NERExtractor` |
|
|
| Build a knowledge graph | `kg` | `GraphBuilder` |
|
|
| Store and search vectors | `vector_store` | `VectorStore` |
|
|
| Give my agent persistent memory | `context` | `AgentContext` |
|
|
| Record AI decisions with audit trail | `context` | `AgentContext.record_decision()` |
|
|
| Query my graph with natural language | `reasoning` | `GraphReasoner` |
|
|
| Export to RDF / Neo4j / Parquet | `export` | `RDFExporter`, `LPGExporter` |
|
|
| Visualize a knowledge graph | `visualization` | `KGVisualizer` |
|
|
| Run a reproducible pipeline | `pipeline` | `PipelineBuilder` |
|
|
| Use Semantica from Claude Desktop | `mcp_server` | `semantica-mcp` |
|
|
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Core Concepts" icon="book-open" href="concepts">
|
|
Knowledge graphs, ontologies, and reasoning explained in depth.
|
|
</Card>
|
|
<Card title="Quickstart Tutorial" icon="play" href="quickstart">
|
|
Full 6-step pipeline walkthrough with working code.
|
|
</Card>
|
|
<Card title="Module Reference" icon="puzzle-piece" href="modules">
|
|
Every module, class, and common chain explained.
|
|
</Card>
|
|
<Card title="API Reference" icon="code" href="reference/context">
|
|
Complete module documentation for every class and method.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
|
|
## Help
|
|
|
|
<CardGroup cols={3}>
|
|
<Card title="Discord" icon="discord" href="https://discord.gg/sV34vps5hH">
|
|
Ask questions, share projects, get community support.
|
|
</Card>
|
|
<Card title="GitHub Issues" icon="github" href="https://github.com/semantica-agi/semantica/issues">
|
|
Report bugs or request features.
|
|
</Card>
|
|
<Card title="FAQ" icon="circle-question" href="faq">
|
|
Common questions answered.
|
|
</Card>
|
|
</CardGroup>
|