# Prerequisites for Running Semantica AGI: System Requirements and Installation Guide

> Discover the prerequisites for running Semantica AGI. Learn about system requirements like Python version, RAM, disk space, and OS compatibility. Optimize your setup today.

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

---

**To run Semantica AGI, you need Python 3.8 or higher, at least 4 GB of RAM and 2 GB of disk space, and a compatible operating system (Windows, Linux, or macOS), with optional GPU support and LLM provider SDKs available through pip extras.**

Semantica AGI is a pure-Python framework designed for building semantic pipelines, knowledge graphs, and agent contexts. Before you can begin ingesting documents or running GraphRAG queries in the `semantica-agi/semantica` repository, your workstation must meet specific minimum prerequisites and you must configure the appropriate optional dependencies for your target workload.

## Minimum System Requirements

The framework maintains modest baseline requirements documented in [`docs/installation.md`](https://github.com/semantica-agi/semantica/blob/main/docs/installation.md), but production deployments handling large language models or extensive vector indices demand significantly more resources.

### Python Version

You must have **Python 3.8 or higher** installed. While the core library runs on 3.8, the development team recommends **Python 3.11+** for optimal performance and compatibility with modern language features. You can verify your version before installation:

```bash
python -c "import sys; print(sys.version)"

```

### Operating System Support

Semantica AGI runs on **Windows, Linux, and macOS**. However, Linux and macOS environments provide the full feature set, particularly for GPU acceleration and certain system-level integrations. Windows users may encounter limitations with specific visualization backends or CUDA tooling.

### Memory and Storage Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| **RAM** | 4 GB | 16 GB+ (required for large models or GPU pipelines) |
| **Disk Space** | 2 GB (library only) | 20 GB+ (for models, vector indices, and datasets) |

## Optional Dependencies and Installation Extras

The core `semantica` package operates without external dependencies, but real-world applications require specific extras installed via `pip install semantica[<extra>]`. These extras are defined in the package configuration and listed in the installation documentation.

### Available Extras

| Extra | Dependencies Added | Use Case |
|-------|-------------------|----------|
| `semantica[gpu]` | PyTorch + CUDA, FAISS-GPU, CuPy | Large-scale embeddings and GPU-accelerated similarity search |
| `semantica[viz]` | PyVis, Graphviz, UMAP | Interactive graph visualizations and embedding plots |
| `semantica[llm-openai]` | OpenAI SDK + credential handling | GPT-based semantic extraction and reasoning |
| `semantica[llm-anthropic]` | Anthropic SDK | Claude-powered agent contexts |
| `semantica[llm-gemini]` | Google Gemini SDK | Multimodal LLM integration |
| `semantica[llm-groq]` | Groq SDK | High-speed inference APIs |
| `semantica[llm-ollama]` | Ollama client | Local open-source model hosting |
| `semantica[cloud]` | AWS S3, Azure Blob, GCS clients | Cloud object storage persistence |
| `semantica[all]` | All packages listed above | Complete feature set for experimentation |

Install multiple extras by combining them:

```bash
pip install semantica[gpu,viz,llm-openai]

```

## Setting Up Your Development Environment

The `semantica-agi/semantica` source code assumes isolated Python environments. Installing directly into system Python is not recommended due to dependency conflicts with ML libraries.

### Virtual Environment Setup

Create and activate a virtual environment before installation:

```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS

# Windows: venv\Scripts\activate

pip install semantica[all]  # Or select specific extras

```

### Conda Alternative

If you prefer Conda, create a dedicated environment with Python 3.11:

```bash
conda create -n semantica python=3.11
conda activate semantica
pip install semantica[all]

```

### Installation Verification

After installation, verify the package loads correctly by checking the version exposed in [`semantica/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/__init__.py):

```bash
python -c "import semantica; print(semantica.__version__)"  # Outputs: 0.6.5

```

## Hardware Considerations for Production Workloads

### GPU Support Requirements

The `[gpu]` extra requires a **CUDA-compatible NVIDIA GPU** with appropriate drivers installed. If GPU installation fails during `pip install semantica[gpu]`, install the CPU-only base package first, then retry the GPU extras:

```bash
pip install semantica
pip install semantica[gpu]

```

According to the source configuration, the `VectorStore` class in the codebase auto-detects GPU availability when initialized with FAISS backend:

```python
from semantica.vector_store import VectorStore

store = VectorStore(backend="faiss", dimension=768)  # GPU backend auto-detected

```

### Memory Management for Large Graphs

When building extensive knowledge graphs or executing multi-hop GraphRAG queries, allocate at least **16 GB RAM**. The `GraphBuilder` class and related components in the semantic extraction pipeline load entities and relationships into memory during construction, which can exhaust available RAM on 4-8 GB systems.

## Verifying Your Installation with a Minimal Pipeline

Test your prerequisites by running a pattern-based extraction pipeline that requires no API keys. This example uses core components from `semantica/ingest`, `semantica/parse`, and `semantica/semantic_extract`:

```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 a PDF document

doc = FileIngestor().ingest("data/report.pdf")[0]

# 2. Parse the raw document structure

parsed = DocumentParser().parse(doc)

# 3. Extract entities and relations using pattern-based methods

entities = NERExtractor(method="pattern").extract(parsed)
relations = RelationExtractor().extract(parsed, entities=entities)

# 4. Construct the knowledge graph with entity merging enabled

graph = GraphBuilder(merge_entities=True).build(
    {"entities": entities, "relationships": relations}
)
print(f"Graph contains {len(graph['entities'])} nodes, {len(graph['relationships'])} edges")

```

If this script executes without `ImportError` or memory exceptions, your environment satisfies all runtime prerequisites.

## Key Source Files for Prerequisites

The following files in the `semantica-agi/semantica` repository contain the authoritative implementation details for system requirements:

- **[`docs/installation.md`](https://github.com/semantica-agi/semantica/blob/main/docs/installation.md)** – Contains the complete dependency matrix and installation commands referenced throughout this guide.
- **[`semantica/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/__init__.py)** – Exposes the top-level API and handles lazy-loading of sub-modules; contains the `__version__` string used for verification.
- **[`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)** – Implements the MCP server providing 100+ RPC endpoints; requires specific optional dependencies when running in server mode.
- **[`semantica/visualization/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/config.py)** – Central configuration for visualization backends; validates that PyVis and Graphviz are present when `[viz]` extras are requested.
- **[`ARCHITECTURE.md`](https://github.com/semantica-agi/semantica/blob/main/ARCHITECTURE.md)** – High-level documentation of the data pipeline and storage layers, including hardware recommendations for each processing stage.

## Summary

- **Python 3.8+ is required**, though 3.11+ is strongly recommended for optimal performance.
- **Minimum hardware** includes 4 GB RAM and 2 GB disk, but production workloads need 16 GB+ RAM and 20 GB+ storage.
- **Install via virtual environments** using `pip install semantica[<extra>]` with extras like `[gpu]`, `[viz]`, or `[llm-openai]` matching your use case.
- **GPU acceleration** requires CUDA-compatible hardware and the `[gpu]` extra for FAISS-GPU and PyTorch support.
- **Verification** can be performed using pattern-based extraction classes that require no external API keys.

## Frequently Asked Questions

### Can I run Semantica AGI without a GPU?

Yes. The core framework runs entirely on CPU. Install the base package with `pip install semantica` and use pattern-based extraction methods or CPU-compatible LLM providers. The `[gpu]` extra is only required for FAISS-GPU acceleration and large-scale embedding operations.

### Which Python version is optimal for Semantica AGI?

Python 3.11 or higher provides the best performance and compatibility. While Python 3.8 meets the minimum requirement, newer versions offer significant improvements in async handling and memory management used by the [`semantica/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py) implementation.

### How do I install multiple optional extras at once?

Combine extras in a comma-separated list within the brackets: `pip install semantica[gpu,viz,llm-openai]`. To install all available extras including cloud providers and all LLM SDKs, use `pip install semantica[all]` as documented in [`docs/installation.md`](https://github.com/semantica-agi/semantica/blob/main/docs/installation.md).

### Where can I find the specific dependency versions required?

The exact version constraints for PyTorch, CUDA, FAISS, and provider SDKs are specified in [`docs/installation.md`](https://github.com/semantica-agi/semantica/blob/main/docs/installation.md) and the package configuration files. The [`semantica/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/__init__.py) file also implements runtime checks that raise `ImportError` with specific installation instructions if optional dependencies are missing.