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

> Learn how to set up Semantica AGI locally. Install via pip, verify your environment, and build a Knowledge Graph or deploy the full stack using Docker Compose.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-13

---

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

```bash

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

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py) for decision tracking and [`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/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.

```bash
semantica doctor

```

This command checks Python version compatibility, package version consistency, and default vector store availability. According to the source in [`README.md`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/docs/quickstart.md).

### Step 1: Ingest Raw Documents

Use `FileIngestor` from [`semantica/ingest/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/__init__.py) to load PDFs, DOCX files, HTML, or other supported formats.

```python
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.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py).

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/__init__.py).

```python
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.

```python
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.

```bash
docker compose up -d

```

This provisions the MCP server ([`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/__init__.py)** – Entry points for all ingestion backends including files, web scraping, and databases.
- **[`semantica/semantic_extract/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/__init__.py)** – APIs for entity recognition and relationship extraction.
- **[`semantica/kg/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/__init__.py)** – Graph construction utilities and analysis tools.
- **[`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py)** – Core `ContextGraph` class for recording decisions and linking provenance.
- **[`semantica/visualization/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/__init__.py)** – Interactive visualization components for local graph exploration.
- **[`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)** – MCP server exposing 100+ REST endpoints for external integration.
- **[`docker-compose.yml`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)) or the Knowledge Explorer web interface.