semantica/docs/learning-more.md

title, description, icon

title	description	icon
Learning More	Structured learning paths, configuration reference, troubleshooting, and performance guidance.	graduation-cap

Structured paths for going from beginner to production with Semantica.

---

Learning Paths

New to Semantica and knowledge graphs. [Start with Installation](installation) Comfortable with basics, building production apps. [Start with Modules](modules) Enterprise applications and customization. [Start with Architecture](architecture)

---

Beginner Path

1. Installation Guide — set up your environment
2. Core Concepts — understand KGs, embeddings, and extraction
3. Getting Started — first working example
4. Quickstart Tutorial — build your first KG
5. Welcome to Semantica notebook — interactive introduction

---

Intermediate Path

1. Modules Guide — every module with code examples
2. Building Knowledge Graphs notebook
3. Embeddings notebook
4. GraphRAG Complete notebook
5. Multi-Source Data Integration notebook
6. Use Cases — domain-specific examples

---

Advanced Path

1. Architecture Guide — three-layer system overview
2. Temporal Graphs notebook — v0.4.0 temporal intelligence
3. Ontology notebook — v0.5.0 Ontology Hub
4. Complete Visualization Suite notebook
5. Multi-Format Export notebook
6. Deep Dive — internals and extension points

---

Configuration Reference

Setting	Environment Variable	Default
OpenAI API Key	OPENAI_API_KEY	None
Groq API Key	GROQ_API_KEY	None
Embedding Provider	SEMANTICA_EMBEDDING_PROVIDER	"openai"
Graph Backend	SEMANTICA_GRAPH_BACKEND	"networkx"
Log Level	SEMANTICA_LOG_LEVEL	"INFO"
Log Format	SEMANTICA_LOG_FORMAT	"text"

---

Troubleshooting

ModuleNotFoundError

Verify installation: pip list | grep semantica. Ensure Python 3.8+. For optional extras, install the relevant extra (e.g. pip install "semantica[llm-openai]").

AuthenticationError

Set the relevant API key as an environment variable (OPENAI_API_KEY, GROQ_API_KEY, etc.). Never hardcode keys in source files.

MemoryError or OOM crashes

Reduce batch sizes or switch to a persistent graph backend (Neo4j, FalkorDB) instead of the default in-memory NetworkX backend.

Slow processing on large datasets — enable parallel processing via Pipeline(workers=N) and use GPU acceleration for embedding models.

Windows [all] installation fails (v0.5.0 fix)

Use pip install "semantica[core]" instead of pip install "semantica[all]" on Windows. See the Installation guide for the full list of extras.

cp1252 encoding crash on Windows (v0.5.0 fix) — pass encoding="utf-8" explicitly to FileIngestor or set PYTHONIOENCODING=utf-8 in your environment.

---

Performance Optimization

Batch processing — process documents in batches rather than one at a time; configure chunk sizes based on available RAM.

Parallel execution — Pipeline(workers=N) runs extraction steps in parallel across documents.

Backend selection:

Operation	NetworkX	Neo4j / FalkorDB
Graph construction	Fast	Moderate
Query performance	Moderate	Fast
Scalability	Low (in-memory)	High (persistent)

Use NetworkX for development and small graphs; switch to a persistent backend for production.

---

Security Best Practices

API keys — store in environment variables or a secrets manager; never commit them to version control; rotate regularly.

Data privacy — use local embedding models (Ollama, HuggingFace) for sensitive data; avoid sending PII to external APIs without appropriate data handling agreements.

Exports — encrypt sensitive graph exports at rest; use the v0.5.0 SSRF-safe base_url validation when configuring custom LLM gateways.

---

See Also

Interactive Jupyter notebook tutorials. Common questions answered. Complete technical documentation. Real-world domain examples.