semantica/docs/faq.md

title, description, icon

title	description	icon
FAQ	Common questions about Semantica — installation, features, integrations, and troubleshooting.	circle-question

General

Semantica is an open-source framework for building context graphs and decision intelligence layers for AI. It transforms unstructured data — documents, APIs, databases — into structured knowledge graphs with full provenance tracking, making AI systems explainable and auditable.

• Knowledge graphs from documents and multi-source data
• GraphRAG systems with graph-grounded retrieval
• AI agents with structured decision history and semantic memory
• Compliance-ready pipelines with W3C PROV-O lineage

Most frameworks stop at retrieval or generation. Semantica adds an **accountability layer**: every decision is recorded, every fact links to a source, and every reasoning step is explainable. It's designed for environments where you need to audit *why* an AI reached a conclusion — not just what it said. Yes — MIT licensed, no vendor lock-in. Some features require third-party API keys (e.g., OpenAI embeddings), but Semantica itself is always free.

v0.5.0 — released May 2026. Highlights: Ontology Hub, Distance Intelligence, Parquet/XML ingestion, 12 security fixes, Graph Explorer redesign.

pip install --upgrade semantica

---

Installation

pip install semantica

See Installation for virtual environment setup, optional extras ([gpu], [all], provider-specific), and troubleshooting.

Python **3.8 or higher**. Python 3.11+ is recommended for best performance. This was a known bug — fixed in **v0.5.0**. Upgrade:

pip install --upgrade semantica

Requirement	Minimum	Recommended
Python	3.8	3.11+
RAM	4 GB	16 GB+
GPU	Optional	CUDA for embeddings / ML

---

Data & Features

Category	Sources
Files	PDF, DOCX, HTML, JSON, CSV, Excel, PPTX, Parquet (v0.5.0), XML (v0.5.0), archives
Web	WebIngestor crawl, RSS feeds
Databases	PostgreSQL, MySQL, Snowflake via DBIngestor / SnowflakeIngestor
Streams	Kafka, real-time ingestion
Protocols	MCP (Model Context Protocol)

Yes. Semantica supports custom entity extraction models, embedding models, LLM providers via LiteLLM (100+ models), and custom pipeline processors via the `PluginRegistry`. Yes. When available, GPUs are used automatically for embedding generation, ML model inference, and vector operations.

pip install "semantica[gpu]"

• Batching — process documents in configurable chunks
• Parallel processing — Pipeline supports configurable worker counts
• Delta processing — update graphs incrementally without full recompute
• Graph backends — swap in-memory NetworkX for Neo4j, FalkorDB, or Apache AGE at scale

`TemporalKnowledgeGraph` attaches `valid_from`/`valid_until` to nodes and edges. Supports point-in-time queries, all 13 Allen interval algebra relations, and OWL-Time export.

from semantica.kg import TemporalKnowledgeGraph

tkg = TemporalKnowledgeGraph()
tkg.add_temporal_triple("A", "caused", "B", valid_from="2024-01", valid_until="2024-06")
snapshot = tkg.query_at_time("2024-03")

A visual browser UI for the full ontology lifecycle — visual editor, SHACL Studio, alignment authoring, health dashboard, and version control. Launch via `semantica.explorer`. Semantic neighborhood exploration for any graph node: N×N distance matrices, ego-mode visualization, distance band classification (`near`/`mid`/`far`), and embedding cache optimization. Fixed in **v0.5.0**. The `response_format=json_object` parameter is now conditionally omitted for incompatible gateways, and a plain `generate()` + JSON parsing fallback is used automatically. Upgrade to fix.

---

Technical

Neo4j, FalkorDB, Apache AGE (PostgreSQL), Amazon Neptune, and in-memory NetworkX for development. RDF (Turtle, JSON-LD, N-Triples, XML), Apache Parquet, ArangoDB AQL, CSV, YAML, and OWL ontologies. FAISS, Pinecone, Weaviate, Qdrant, Milvus, PgVector, and in-memory. Groq, OpenAI, Anthropic, Google Gemini, Ollama (local), DeepSeek, Novita AI, LiteLLM (100+ models), and any OpenAI-compatible gateway. Yes. v0.5.0 ships with:

• 1,000+ passing tests
• PipelineValidator and FailureHandler with exponential backoff
• W3C PROV-O provenance tracking
• Change management with SHA-256 checksums
• 12 security vulnerability fixes (eval injection, pickle deserialization, SQL injection, XXE, SSRF, ReDoS, path traversal, and more)

---

Troubleshooting

Ensure you have the correct Python environment active:

pip list | grep semantica
pip install --upgrade semantica

pip install --upgrade pip wheel
pip install semantica

Reduce batch sizes, enable streaming ingestion, or switch to a persistent graph backend (Neo4j, FalkorDB). Install GPU support and ensure CUDA is available:

pip install "semantica[gpu]"

Fixed in **v0.5.0**. Upgrade:

pip install --upgrade semantica

---

Support

Community chat and live support. Bug reports and feature requests. Help improve Semantica.