How to Set Up Semantica AGI Locally: Complete Installation and Pipeline Guide

To set up Semantica AGI locally, install the Python package via pip install semantica, verify your environment with semantica doctor, and run the data pipeline using FileIngestor and GraphBuilder to construct a Knowledge Graph from your documents, or deploy the full stack using Docker Compose for a self-hosted REST API and web interface.

Semantica AGI is a graph-native infrastructure that transforms raw data into Context and Knowledge Graphs beneath your LLM and agent frameworks. As implemented in the semantica-agi/semantica repository, it provides deterministic reasoning, provenance tracking, and decision intelligence—all runnable locally without external dependencies. This guide walks you through installation, verification, and your first end-to-end pipeline using the exact module paths and classes defined in the source code.

Install Semantica AGI Locally

You can install the core library via pip for immediate use or clone the repository for development and customization.

Install from PyPI

The fastest path to a local setup uses pip with optional extras for databases and vector stores.

# Core package only

pip install semantica

# Full installation with database connectors, vector stores, and extras

pip install semantica[all]

This installs the complete ingestion, parsing, and graph construction stack accessible through semantica.ingest, semantica.parse, and semantica.kg modules.

Install from Source

For custom modifications or contributions, clone the repository and install in editable mode.

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

This approach gives you direct access to files like semantica/context.py for decision tracking and semantica/mcp/server.py for the REST API endpoints.

Verify Your Installation

Before processing data, confirm your environment is correctly configured using the built-in diagnostic tool.

semantica doctor

This command checks Python version compatibility, package version consistency, and default vector store availability. According to the source in README.md, this is the recommended first step to validate local setup in under five seconds.

Build Your First Knowledge Graph Locally

Once installed, you can execute the full data pipeline—from ingestion to graph construction—using the core classes defined in the semantica package. The following reproducible script mirrors the pipeline stages documented in docs/quickstart.md.

Step 1: Ingest Raw Documents

Use FileIngestor from semantica/ingest/__init__.py to load PDFs, DOCX files, HTML, or other supported formats.

from semantica.ingest import FileIngestor

ingestor = FileIngestor()
sources = ingestor.ingest("data/report.pdf")  # Supports multiple formats and paths

Step 2: Parse and Prepare Content

Pass the ingested sources to DocumentParser to extract structured text.

from semantica.parse import DocumentParser

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

Step 3: Extract Entities and Relationships

Perform pattern-based extraction (no LLM API key required) using classes from semantica/semantic_extract/__init__.py.

from semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor

# Pattern-based NER

ner = NamedEntityRecognizer(method="pattern")
entities = ner.extract(parsed)

# Rule-based relation extraction

rel = RelationExtractor(method="rule")
relationships = rel.extract(parsed, entities=entities)

Step 4: Construct the Knowledge Graph

Build the graph with automatic deduplication and conflict resolution using GraphBuilder from semantica/kg/__init__.py.

from semantica.kg import GraphBuilder

builder = GraphBuilder(merge_entities=True)
graph = builder.build({
    "entities": entities, 
    "relationships": relationships
})

print(f"Graph built: {len(graph['entities'])} nodes, {len(graph['relationships'])} edges")

Visualize and Export Locally

After construction, visualize the graph using KGVisualizer or export to standard formats.

from semantica.visualization import KGVisualizer
from semantica.export import RDFExporter

# Generate interactive HTML visualization

viz = KGVisualizer(layout="force")
viz.visualize_network(
    graph, 
    output="html", 
    file_path="graph.html", 
    node_color_by="type"
)

# Export to RDF/Turtle format

exporter = RDFExporter()
exporter.export(graph, file_path="graph.ttl", format="turtle")

Deploy the Full Stack with Docker

For a complete self-hosted environment including the REST API and Knowledge Explorer UI, use the provided Docker configuration.

docker compose up -d

This provisions the MCP server (semantica/mcp/server.py), a FAISS in-memory vector store, and a Neo4j graph store. The REST API becomes available at http://localhost:8000, with the Knowledge Explorer UI served at http://localhost:3000. The docker-compose.yml file at the repository root defines these services for immediate local deployment.

Core Architecture for Local Deployment

Setting up Semantica AGI locally means running a linear data pipeline followed by an intelligence layer. As documented in ARCHITECTURE.md, the pipeline flows through:

• Ingestion: FileIngestor, WebIngestor, DBIngestor (semantica.ingest)
• Parsing: DocumentParser, DoclingParser (semantica.parse)
• Normalization: TextNormalizer, EntityNormalizer (semantica.normalize)
• Chunking: TextSplitter with entity-aware and graph-based strategies (semantica.split)
• Extraction: NamedEntityRecognizer, RelationExtractor, TripletExtractor (semantica.semantic_extract)
• Conflict Resolution: ConflictDetector, EntityMerger (semantica.conflicts, semantica.deduplication)
• Knowledge Graph: GraphBuilder, BiTemporalFact (semantica.kg)
• Intelligence: ReteEngine, ProvenanceManager, ContextGraph (semantica.reasoning, semantica.context)

This architecture enables deterministic reasoning and audit-ready decision tracking without cloud dependencies.

Key Source Files to Explore

When running Semantica AGI locally, these entry points control specific functionality:

• semantica/ingest/__init__.py – Entry points for all ingestion backends including files, web scraping, and databases.
• semantica/semantic_extract/__init__.py – APIs for entity recognition and relationship extraction.
• semantica/kg/__init__.py – Graph construction utilities and analysis tools.
• semantica/context.py – Core ContextGraph class for recording decisions and linking provenance.
• semantica/visualization/__init__.py – Interactive visualization components for local graph exploration.
• semantica/mcp/server.py – MCP server exposing 100+ REST endpoints for external integration.
• docker-compose.yml – Orchestration for the full self-hosted stack.

Summary

• Install Semantica AGI locally using pip install semantica or pip install -e ".[dev]" from source.
• Verify your environment with semantica doctor to check dependencies and vector store availability.
• Ingest documents via FileIngestor, then parse with DocumentParser from semantica.parse.
• Extract entities and relationships using NamedEntityRecognizer and RelationExtractor without requiring API keys.
• Build the Knowledge Graph using GraphBuilder from semantica.kg with automatic deduplication.
• Visualize locally with KGVisualizer or export to RDF using RDFExporter.
• Deploy the full stack using docker compose up -d for REST API access at localhost:8000 and the Knowledge Explorer at localhost:3000.

Frequently Asked Questions

Do I need an LLM API key to run Semantica AGI locally?

No. Semantica AGI supports pattern-based and rule-based extraction methods that operate entirely locally. The NamedEntityRecognizer and RelationExtractor classes accept method="pattern" and method="rule" parameters, allowing you to build Knowledge Graphs using deterministic algorithms without external API calls or costs.

What databases and storage options work with local deployment?

The local setup supports FAISS for vector storage (in-memory) and Neo4j or FalkorDB for graph persistence, as implemented in semantica.vector_store and semantica.graph_store. The Docker Compose configuration automatically provisions Neo4j, while the Python-only installation uses in-memory stores suitable for development and smaller datasets.

How do I troubleshoot installation issues when setting up locally?

Run semantica doctor immediately after installation to diagnose common issues. This command checks Python version compatibility, verifies the semantica package installation, and tests default vector store availability. For source installations, ensure you use pip install -e ".[dev]" to capture all development dependencies required by the test suite and CLI tools.

Can I process documents without using Docker?

Yes. The Python library is fully functional without Docker. You can ingest files, parse documents, extract entities, and build Knowledge Graphs entirely within a Python script or Jupyter notebook using the semantica.ingest, semantica.parse, and semantica.kg modules. Docker is only required if you need the REST API server (semantica/mcp/server.py) or the Knowledge Explorer web interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}