mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-08-30 04:40:16 +00:00
KaifAhmad1
9113ef3428
- Rewrote all 26 reference module pages: removed blockquote taglines and horizontal rule separators, added "What You Get" bullet summaries, added constructor/method parameter tables, expanded thin files (graph_store, triplet_store, visualization, provenance) with full API coverage, added backend comparison tables and real-world usage patterns - Renamed Modules tab from "API Reference" and group from "Context & Knowledge" to "Context & Intelligence" in docs.json - Fixed logo: copied "Semantica Logo.png" to web-safe semantica-logo.png and updated all 4 references in docs.json - Improved core docs (index, modules, concepts, quickstart, installation, getting-started) with better fonts, bullet points, and complete module listings (mcp_server, evals, core, utils previously missing) - Rewrote community pages (community, community-projects, contributing-guide, use-cases, architecture, faq, learning-more, glossary) with heading hierarchy fixes, expanded definitions, and better structure - Fixed markdown linter warnings: MD036 bold-as-heading, MD001 heading skips, MD040 missing code fence language, MD032 blank lines around lists
186 lines
6.9 KiB
Markdown
186 lines
6.9 KiB
Markdown
---
|
||
title: "Learning More"
|
||
description: "Structured learning paths, configuration reference, troubleshooting, and performance guidance."
|
||
icon: "graduation-cap"
|
||
---
|
||
|
||
Whether you're running your first pipeline or deploying Semantica in production, this page gives you a structured path forward — from beginner to enterprise-grade usage.
|
||
|
||
## Learning Paths
|
||
|
||
<CardGroup cols={3}>
|
||
<Card title="Beginner (1–2 hrs)" icon="seedling">
|
||
New to Semantica and knowledge graphs.
|
||
[Start with Installation →](installation)
|
||
</Card>
|
||
<Card title="Intermediate (4–6 hrs)" icon="compass">
|
||
Comfortable with basics, building real applications.
|
||
[Start with Modules →](modules)
|
||
</Card>
|
||
<Card title="Advanced (8+ hrs)" icon="rocket">
|
||
Enterprise deployments, customization, and extension.
|
||
[Start with Architecture →](architecture)
|
||
</Card>
|
||
</CardGroup>
|
||
|
||
### Beginner Path
|
||
|
||
1. [Installation Guide](installation) — set up your environment
|
||
2. [Core Concepts](concepts) — understand KGs, embeddings, and extraction
|
||
3. [Getting Started](getting-started) — first working example
|
||
4. [Quickstart Tutorial](quickstart) — build your first knowledge graph
|
||
5. [Welcome to Semantica notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/01_Welcome_to_Semantica.ipynb) — interactive introduction to all modules
|
||
|
||
### Intermediate Path
|
||
|
||
1. [Modules Guide](modules) — every module with code examples
|
||
2. [Building Knowledge Graphs notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/07_Building_Knowledge_Graphs.ipynb)
|
||
3. [Embeddings notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/09_Embeddings.ipynb)
|
||
4. [GraphRAG Complete notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/use_cases/advanced_rag/01_GraphRAG_Complete.ipynb)
|
||
5. [Multi-Source Data Integration notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/06_Multi_Source_Data_Integration.ipynb)
|
||
6. [Use Cases](use-cases) — domain-specific examples with notebooks
|
||
|
||
### Advanced Path
|
||
|
||
1. [Architecture Guide](architecture) — three-layer system, extension points, design decisions
|
||
2. [Temporal Graphs notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/04_Temporal_Graphs.ipynb) — v0.4.0 temporal intelligence
|
||
3. [Ontology notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/14_Ontology.ipynb) — v0.5.0 Ontology Hub
|
||
4. [Complete Visualization Suite notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/03_Complete_Visualization_Suite.ipynb)
|
||
5. [Multi-Format Export notebook](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/05_Multi_Format_Export.ipynb)
|
||
|
||
## Configuration Reference
|
||
|
||
All settings can be overridden with environment variables — no code changes needed.
|
||
|
||
| Setting | Environment Variable | Default |
|
||
| ------- | -------------------- | ------- |
|
||
| OpenAI API Key | `OPENAI_API_KEY` | `None` |
|
||
| Groq API Key | `GROQ_API_KEY` | `None` |
|
||
| Anthropic API Key | `ANTHROPIC_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: No module named 'semantica'`
|
||
|
||
Verify installation and that the correct Python environment is active:
|
||
|
||
```bash
|
||
pip list | grep semantica
|
||
pip install --upgrade semantica
|
||
```
|
||
|
||
For optional features, install the relevant extra:
|
||
|
||
```bash
|
||
pip install "semantica[llm-openai]" # OpenAI provider
|
||
pip install "semantica[gpu]" # GPU acceleration
|
||
```
|
||
|
||
### `AuthenticationError`
|
||
|
||
Set your API key as an environment variable — never hardcode keys in source files:
|
||
|
||
```bash
|
||
export OPENAI_API_KEY="sk-..."
|
||
export GROQ_API_KEY="gsk_..."
|
||
```
|
||
|
||
### `MemoryError` or OOM crashes
|
||
|
||
Switch from the default in-memory NetworkX backend to a persistent graph database:
|
||
|
||
```python
|
||
from semantica.graph_store import FalkorDBStore
|
||
from semantica.kg import GraphBuilder
|
||
|
||
store = FalkorDBStore(host="localhost", port=6379)
|
||
builder = GraphBuilder(merge_entities=True, graph_store=store)
|
||
```
|
||
|
||
Also reduce batch sizes and enable streaming ingestion for large corpora.
|
||
|
||
### Slow processing on large datasets
|
||
|
||
Enable parallel execution and GPU acceleration:
|
||
|
||
```python
|
||
from semantica.pipeline import Pipeline
|
||
|
||
pipeline = Pipeline(workers=8, batch_size=32)
|
||
pipeline.run(sources)
|
||
```
|
||
|
||
```bash
|
||
pip install "semantica[gpu]" # CUDA-backed embeddings
|
||
```
|
||
|
||
### Windows `[all]` installation fails
|
||
|
||
Fixed in **v0.5.0**. Upgrade:
|
||
|
||
```bash
|
||
pip install --upgrade semantica
|
||
```
|
||
|
||
Or install extras individually: `pip install "semantica[core]"`, then add `[llm-openai]`, `[gpu]`, etc. as needed.
|
||
|
||
### cp1252 encoding crash on Windows
|
||
|
||
Fixed in **v0.5.0**. For earlier versions, pass encoding explicitly or set the environment variable:
|
||
|
||
```bash
|
||
set PYTHONIOENCODING=utf-8
|
||
```
|
||
|
||
## Performance Optimization
|
||
|
||
### Backend Selection
|
||
|
||
| Operation | NetworkX (default) | Neo4j / FalkorDB |
|
||
| --------- | ------------------ | ---------------- |
|
||
| Graph construction | Fast | Moderate |
|
||
| Query performance | Moderate | Fast |
|
||
| Scalability | Low — in-memory only | High — persistent |
|
||
| Recommended for | Development, small graphs | Production, large corpora |
|
||
|
||
Use NetworkX for local development and prototyping. Switch to a persistent backend before deploying to production.
|
||
|
||
### Batch Processing
|
||
|
||
Process documents in batches rather than one at a time. Configure `chunk_size` based on available RAM — a good starting point is 1,000 documents per batch on a 16 GB machine.
|
||
|
||
### Deduplication v2
|
||
|
||
If deduplication is a bottleneck, switch from v1 strategies to v2:
|
||
|
||
```python
|
||
resolver = EntityResolver()
|
||
merged = resolver.resolve(entities, strategy="semantic_v2") # up to 7x faster
|
||
```
|
||
|
||
## Security Best Practices
|
||
|
||
- **API keys** — store in environment variables or a secrets manager; never commit them to version control; rotate on a schedule
|
||
- **Sensitive data** — use local embedding models (Ollama, HuggingFace) for PII or classified content; avoid sending sensitive data to external APIs without data handling agreements
|
||
- **Graph exports** — encrypt sensitive exports at rest; use the v0.5.0 SSRF-safe `base_url` validation when configuring custom LLM gateways
|
||
- **XML ingestion** — always use `XMLIngestor` (v0.5.0), which uses the XXE-safe lxml backend; never parse untrusted XML with the standard library parser
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="Cookbook" icon="flask" href="cookbook">
|
||
Interactive Jupyter notebooks from beginner to advanced.
|
||
</Card>
|
||
<Card title="FAQ" icon="circle-question" href="faq">
|
||
Common questions answered.
|
||
</Card>
|
||
<Card title="API Reference" icon="code" href="reference/core">
|
||
Complete technical documentation.
|
||
</Card>
|
||
<Card title="Use Cases" icon="briefcase" href="use-cases">
|
||
Domain-specific examples with notebooks.
|
||
</Card>
|
||
</CardGroup>
|