# How to Build Semantica AGI from Source: Complete Installation Guide

> Learn how to build Semantica AGI from source with our complete installation guide. Clone the repository, install core and optional dependencies, and verify your build easily.

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

---

**To build Semantica AGI from source, clone the `semantica-agi/semantica` repository, install the core package in editable mode via `pip install -e .`, add optional backend dependencies using extras like `[faiss]` or `[neo4j]`, and verify the build with the `semantica doctor` CLI command.**

Semantica AGI is a modular, graph-native platform that provides deterministic context graphs, decision provenance, and ontology management for LLM-based agents. Building from source gives you full access to the complete pipeline—from raw data ingestion through knowledge graph construction to REST-MCP serving. This guide walks you through compiling the platform from the official repository and configuring its polyglot storage backends.

## Prerequisites

Before you begin building Semantica AGI from source, ensure your environment meets the baseline requirements.

- **Python 3.8 or higher** is required for core compatibility.
- **Git** is necessary to clone the repository.
- A **C compiler** may be required for optional native extensions like FAISS.

## Step-by-Step Build Instructions

Follow these steps to compile and install Semantica AGI from the source code.

### Clone the Repository

First, download the source code from the official GitHub repository.

```bash
git clone https://github.com/semantica-agi/semantica.git
cd semantica

```

### Create a Virtual Environment

Isolate your dependencies to prevent conflicts with system packages.

```bash
python -m venv .venv
source .venv/bin/activate

```

### Install the Core Package

Install Semantica in editable mode. This compiles any optional C-extensions and registers CLI entry-points as defined in [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml).

```bash
pip install -e .

```

### Install Optional Backend Dependencies

Semantica AGI uses an extensible backend system. Install only the extras you need for your specific deployment. Each backend is available as a pip extra defined in the source [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml).

**Vector Store Backends:**

```bash
pip install "semantica[faiss]"      # FAISS for CPU-based similarity search

pip install "semantica[qdrant]"     # Qdrant RPC client

pip install "semantica[neo4j]"      # Neo4j graph database driver

pip install "semantica[weaviate]"   # Weaviate vector search

```

**Enterprise Data Platform Connectors:**

```bash
pip install "semantica[db-databricks]"  # Databricks Unity Catalog integration

pip install "semantica[db-snowflake]"   # Snowflake connector

```

**Multi-Agent Integrations:**

```bash
pip install "semantica[agno]"        # Agno shared context for multi-agent systems

```

### Verify the Installation

Run the built-in sanity check to confirm that the core package and optional components are functional.

```bash
semantica doctor

```

Expected output includes Python version, Semantica version, backend statuses, and configuration file locations.

## Understanding the Modular Architecture

Semantica AGI is organized as a pipeline of independent, importable modules. Each layer handles a specific stage of the knowledge graph lifecycle.

| Layer | Purpose | Core Package | Typical Entry Points |
|------|---------|--------------|----------------------|
| **Ingestion** | Pull data from files, web, databases, and streams | `semantica.ingest` | `FileIngestor()`, `WebIngestor()`, `DatabricksIngestor()` |
| **Normalization & Chunking** | Clean documents and split with entity-aware boundaries for GraphRAG | `semantica.normalize`, `semantica.split` | `TextSplitter(method="entity_aware")` |
| **Semantic Extraction** | Named entity recognition, relation detection, and triplet generation | `semantica.semantic_extract` | `NamedEntityRecognizer()` in [`semantica/semantic_extract/ner.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract/ner.py) |
| **Conflict Detection** | Flag contradictory facts and merge duplicate entities | `semantica.conflicts`, `semantica.deduplication` | `ConflictDetector()`, `DuplicateDetector()` |
| **Knowledge Graph Construction** | Assemble entities into a bi-temporal KG | `semantica.kg` | `GraphBuilder().build(sources)` in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) |
| **Ontology & Reasoning** | OWL generation, SHACL validation, and forward-chaining | `semantica.ontology`, `semantica.reasoning` | `OntologyGenerator()`, `ReteEngine()` in [`semantica/reasoning/rete_engine.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning/rete_engine.py) |
| **Decision Intelligence** | Record decisions as first-class graph nodes | `semantica.context` | `ContextGraph` class in [`semantica/context/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/__init__.py) |
| **Vector & Polyglot Store** | Hybrid semantic search with pluggable backends | `semantica.vector_store` | `VectorStore(backend="faiss")` in [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py) |
| **Provenance & Export** | W3C PROV-O lineage and RDF export | `semantica.provenance`, `semantica.export` | `RDFExporter()` in [`semantica/export/rdf_exporter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/rdf_exporter.py) |
| **Visualization** | Interactive force-directed graphs and dashboards | `semantica.visualization` | `KGVisualizer()` |
| **MCP Server** | REST-MCP protocol for multi-client access | `semantica.mcp` | [`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py) |

## Starting the Platform

Once built, you can launch the MCP server or use the CLI to interact with the platform.

Start the MCP server (defaults to port 8000):

```bash
semantica start-server

```

Launch the interactive visualization workbench:

```bash
semantica viz

```

Access the server programmatically via HTTP:

```python
import requests

resp = requests.get("http://localhost:8000/api/v1/graph")
graph_json = resp.json()

```

## Practical Code Examples

### Recording Decisions with ContextGraph

The `ContextGraph` class in [`semantica/context/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/__init__.py) provides the core interface for decision provenance.

```python
from semantica.context import ContextGraph

# Initialize with advanced analytics enabled

graph = ContextGraph(advanced_analytics=True)

# Record a regulated decision with full provenance

decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

# Create causal links between decisions

graph.add_causal_relationship(decision_id, "some_next_id", relationship_type="CAUSED")

# Query decision chains and precedents

chain = graph.trace_decision_chain(decision_id)
similar = graph.find_similar_decisions("cloud vendor", max_results=5)

```

### Hybrid Vector Search

Implement semantic search using the unified vector store façade.

```python
from semantica.vector_store import VectorStore, HybridSearch

# Initialize FAISS backend

vs = VectorStore(backend="faiss", dimension=1536)

# Store a decision with embedding

vs.store_decision(
    scenario="Personal loan A-7291, $85k income, 31% DTI",
    outcome="approved",
    confidence=0.94,
    category="loan_underwriting",
)

# Pure dense retrieval

dense_hits = vs.search(query="personal loan approval", limit=5)

# Hybrid dense + sparse search

hs = HybridSearch(vector_store=vs)
hybrid_hits = hs.search("high-risk transactions 2024")

# Explain provenance for audit trails

explanation = vs.explain_decision(hybrid_hits[0]["id"])

```

### Exporting to RDF for Regulatory Compliance

Use `RDFExporter` to generate audit-ready Turtle or JSON-LD files.

```python
from semantica.export import RDFExporter
from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Populate graph with nodes and edges...

kg_dict = graph.to_dict()

# Transform to RDF-compatible structure

kg = {
    "entities": [{"id": n["id"], "type": n["type"], "text": n["content"]} for n in kg_dict["nodes"]],
    "relationships": [
        {"source_id": e["source"], "target_id": e["target"], "type": e["type"]}
        for e in kg_dict["edges"]
    ],
}

# Export to W3C PROV-O compliant Turtle

RDFExporter().export(kg, "audit_trail.ttl", format="turtle")

```

### Running Integration Tests

Validate your source build before production deployment.

```bash
pytest -n auto  # Parallel test execution

```

## Summary

Building Semantica AGI from source provides complete control over the modular pipeline:

- **Clone and install** the core package with `pip install -e .` to register CLI entry-points and compile optional extensions.
- **Select backends** using extras like `[faiss]`, `[neo4j]`, or `[db-snowflake]` to match your infrastructure requirements.
- **Verify functionality** immediately with `semantica doctor` before launching the MCP server or workbench.
- **Leverage the modular architecture** by importing specific layers like `semantica.ingest` or `semantica.reasoning` independently.

## Frequently Asked Questions

### What Python version is required to build Semantica AGI?

Semantica AGI requires **Python 3.8 or higher**. This ensures compatibility with the async features used in [`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py) and the type hints throughout the codebase.

### How do I install only specific vector store backends?

Use pip extras to install only the backends you need. For example, run `pip install "semantica[faiss]"` for local CPU-based search, or `pip install "semantica[qdrant]"` for managed vector databases. The full list of extras is documented in the repository's [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml).

### Where is the MCP server implementation located?

The MCP (Multi-Client Protocol) server is implemented in [`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py). This file contains the REST endpoints for graph access and decision management, which you can launch via the `semantica start-server` CLI command.

### Can I use Semantica AGI with existing multi-agent frameworks?

Yes. The [`integrations/agno/agno_shared_context.py`](https://github.com/semantica-agi/semantica/blob/main/integrations/agno/agno_shared_context.py) module provides the `AgnoSharedContext` class, allowing multiple agents to read from and write to a single `ContextGraph` instance. Install this integration using `pip install "semantica[agno]"`.