How to Install Semantica and Its Dependencies: Complete Setup Guide

Install the core library with pip install semantica and add specific capabilities via optional extras like semantica[documents] or semantica[all] depending on your workload.

Semantica is a modular Python library for knowledge graphs and semantic AI maintained in the semantica-agi/semantica repository. This guide covers how to install Semantica and its dependencies using the layered installation strategy defined in pyproject.toml, ranging from the lightweight core to full production deployments.

Prerequisites

Before installing Semantica, ensure your environment meets the baseline requirements. The library requires Python ≥ 3.9.2 because some core dependencies (such as numpy) no longer publish wheels for older patch versions. Using a virtual environment is strongly recommended to avoid version conflicts with system packages:

python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate

Install the Core Library

The core installation provides the graph engine, provenance tracking, reasoning capabilities, and CLI with only 22 essential dependencies. According to the semantica-agi/semantica source code, these packages are declared under [project.dependencies] in pyproject.toml (lines 48‑96).

Install the core using pip:

pip install semantica

This command pulls in foundational packages including numpy, pandas, scikit-learn, rdflib, networkx, requests, and pydantic. The core contains no heavy ML or visualization stacks, keeping the installation fast and lightweight.

Add Optional Features with Extras

Semantica uses a granular extra system defined under [project.optional-dependencies] in pyproject.toml. Install specific capabilities using the semantica[extra-name] syntax to avoid bloating your environment with unnecessary dependencies.

Document Processing

To parse DOCX, XLSX, PDF, and HTML files, install the documents extra. This group is defined on lines 27‑33 of pyproject.toml:

pip install "semantica[documents]"

Embeddings and Local Models

For local embedding generation without external API calls, use the embeddings-local extra, which includes sentence-transformers, fastembed, and onnxruntime. For HuggingFace model support, add models-huggingface:

# Local embeddings only

pip install "semantica[embeddings-local]"

# With HuggingFace integration

pip install "semantica[models-huggingface]"

Vector Store Backends

Connect to vector databases by installing the specific backend extra. Options include in-memory FAISS or hosted solutions like Qdrant and Pinecone:

# In-memory FAISS

pip install "semantica[vectorstore-faiss]"

# All supported vector stores (Qdrant, Pinecone, Weaviate, etc.)

pip install "semantica[vectorstore-all]"

Graph Database Connectors

Integrate with property graph databases using labeled extras for each backend:

pip install "semantica[graph-neo4j]"        # Neo4j LPG store

pip install "semantica[graph-falkordb]"     # FalkorDB + Redis

pip install "semantica[graph-amazon-neptune]"  # AWS Neptune

pip install "semantica[graph-apache-age]"   # Apache AGE (PostgreSQL)

Database Ingestion

For enterprise data sources, install specific database connectors:

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

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

pip install "semantica[ingest-sap]"        # SAP OData

pip install "semantica[ingest-parquet]"    # Parquet / PyArrow

Install All Extras

For demonstrations or local experimentation, install the complete bundle:

pip install "semantica[all]"

Verify the Installation

After installation, run the built-in health check to confirm which components are available:

semantica doctor

This command prints a status report indicating whether core dependencies are satisfied and which optional extras are detected (e.g., ✔ graph-neo4j available or ✖ vectorstore-faiss missing).

Install From Source

Contributors and users requiring the latest unreleased changes should install from the GitHub repository. The README documents this workflow starting at line 69.

Clone the repository and install in editable mode with development dependencies:

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

The dev extra includes testing frameworks and build tools required for contributing to the codebase.

Deploy with Docker

For production environments, use the provided Dockerfile instead of direct pip installation. The container build process (lines 34‑75) installs the core from pyproject.toml and then adds specific extras using pinned lockfiles (explorer-extra-py313.txt and pep517-build.txt) to ensure reproducible builds.

Build and run the Explorer UI:

docker build -t semantica:latest .
docker run -p 8000:8000 semantica:latest

Summary

• Core installation: pip install semantica provides the graph engine and CLI with 22 essential dependencies defined in pyproject.toml.
• Granular extras: Use bracket syntax (e.g., semantica[documents], semantica[graph-neo4j]) to install only the capabilities you need.
• Verification: Run semantica doctor to check which optional components are available in your environment.
• Production: Use the repository's Dockerfile with lockfiles for reproducible container deployments rather than direct pip installs.

Frequently Asked Questions

What Python version does Semantica require?

Semantica requires Python 3.9.2 or higher. The maintainers dropped support for older Python patches because core dependencies like numpy no longer provide pre-built wheels for them, which would force lengthy source compilations.

How do I install only specific features to keep my Docker image small?

Specify individual extras rather than using [all]. For example, if you only need Neo4j and document parsing, run pip install "semantica[graph-neo4j,documents]". This approach pulls only the necessary transitive dependencies, reducing your final container size by excluding unused ML frameworks or database drivers.

How can I verify that optional dependencies installed correctly?

Run the semantica doctor command after installation. It checks for the presence of each optional extra's underlying packages (like faiss-cpu for vector storage or neo4j for graph connectivity) and reports which features are active.

Can I contribute to Semantica and test my changes locally?

Yes. Clone the repository and install in editable mode with pip install -e ".[dev]". This installs the core plus testing dependencies, allowing you to run pytest tests/ against your modifications. The development install path is documented in the README.md under the "From source" section.

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