Prerequisites for Running Semantica AGI: System Requirements and Installation Guide

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, 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:

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:

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:

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:

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:

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:

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:

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:

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 – Contains the complete dependency matrix and installation commands referenced throughout this guide.
• 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 – Implements the MCP server providing 100+ RPC endpoints; requires specific optional dependencies when running in server mode.
• semantica/visualization/config.py – Central configuration for visualization backends; validates that PyVis and Graphviz are present when [viz] extras are requested.
• 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 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.

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 and the package configuration files. The semantica/__init__.py file also implements runtime checks that raise ImportError with specific installation instructions if optional dependencies are missing.

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