# How to Run the Examples in Semantica AGI: A Complete Guide

> Learn how to run Semantica AGI examples easily. Follow this guide to install dependencies and execute scripts from the semantica-agi repository.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-13

---

**Run any example in the `examples/` directory by installing the package with pip, resolving optional dependencies like `pyarrow` or `pandas`, and executing `python <script>.py` from the repository root.**

The `semantica-agi/semantica` repository ships with a collection of self-contained Python scripts in the `examples/` directory that demonstrate the full end-to-end pipeline. These scripts walk you through data ingestion, semantic extraction, knowledge graph construction, and export workflows. Whether you are testing the **ParquetExporter** or running the comprehensive **Capability-Gap** demo, each script creates a temporary workspace, executes the pipeline, and cleans up automatically.

## Prerequisites and Installation

Before executing any example, you must install the core library and resolve optional dependencies for specific export formats or vector stores.

### Installing the Core Library

Clone the repository and install the base package using pip:

```bash
git clone https://github.com/semantica-agi/semantica.git
cd semantica
pip install -e .

```

This installs the high-level modules used by every example, including the ingestion, parsing, and reasoning engines.

### Resolving Optional Dependencies

Several examples require additional packages for data manipulation and visualization. Install these using the extra tags defined in the project configuration:

- **`[export]`**: Adds `pyarrow` and `pandas` for Parquet and Arrow export
- **`[vector]`**: Adds `faiss` or similar for vector store demonstrations  
- **`[visualization]`**: Adds plotting libraries for `KGVisualizer`

Install all optional extras with:

```bash
pip install -e ".[export,vector,visualization]"

```

## Running the Example Scripts

Each script in the `examples/` directory is executable and prints a status header before running. You launch any demo by calling Python directly on the file.

### The Minimal Export Pattern

The **Parquet Export** example ([`examples/parquet_export_example.py`](https://github.com/semantica-agi/semantica/blob/main/examples/parquet_export_example.py)) provides the simplest entry point. It demonstrates how to use `export_parquet()` from [`semantica/export.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export.py) to persist entities and relationships to columnar storage:

```python

# examples/parquet_export_example.py (simplified)

import tempfile
from pathlib import Path
from semantica.export import export_parquet

def main() -> None:
    out_dir = Path(tempfile.mkdtemp())
    print(f"Output: {out_dir}")

    entities = [
        {"id": "e1", "text": "Alice", "type": "Person", "confidence": 0.95},
        {"id": "e2", "text": "Acme Corp", "type": "Organization", "confidence": 0.88},
    ]
    relationships = [
        {"id": "r1", "source_id": "e1", "target_id": "e2", "type": "WORKS_FOR", "confidence": 0.9}
    ]

    export_path = out_dir / "demo.parquet"
    export_parquet(entities, export_path, compression="snappy")
    print(f"Exported to {export_path}")

if __name__ == "__main__":
    main()

```

Run this script with:

```bash
python examples/parquet_export_example.py

```

The script outputs a temporary directory path containing `demo.parquet`, which you can read back using **pandas** or **pyarrow**.

### End-to-End Pipeline Examples

For a comprehensive demonstration, run the **Capability-Gap Context Graph** example ([`examples/capability_gap_context_graphs_example.py`](https://github.com/semantica-agi/semantica/blob/main/examples/capability_gap_context_graphs_example.py)). This script executes the full Semantica AGI stack:

1. **Ingestion**: Uses `FileIngestor` and `WebIngestor` to load PDFs and web pages
2. **Parsing**: Applies `DocumentParser` and normalization utilities from the parsing module  
3. **Chunking**: Splits text using `TextSplitter` (entity-aware and recursive strategies)
4. **Extraction**: Runs `NamedEntityRecognizer`, `RelationExtractor`, and `TripletExtractor` from [`semantica/semantic_extract.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract.py)
5. **Resolution**: Detects conflicts with `ConflictDetector` and deduplicates via `EntityResolver`
6. **Graph Construction**: Builds the knowledge graph using `GraphBuilder` and analyzes it with `GraphAnalyzer` from [`semantica/kg.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg.py)
7. **Context & Reasoning**: Initializes `ContextGraph` and `AgentContext`, records decisions with `record_decision`, and executes forward-chaining rules via the `Reasoner` class in [`semantica/reasoning.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning.py)
8. **Export**: Persists results using `ParquetExporter` or visualizes with `KGVisualizer` from [`semantica/visualization.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization.py)

Execute the full pipeline:

```bash
python examples/capability_gap_context_graphs_example.py

```

## Understanding the Example Architecture

All examples follow a consistent linear pattern that mirrors production deployment. They import from the same high-level modules you would use in your own applications.

### Data Ingestion and Parsing

Examples ingest raw data through specialized ingestors defined in the ingestion layer. The scripts demonstrate `FileIngestor` for local documents and `WebIngestor` for crawling URLs. After ingestion, `DocumentParser` handles format detection and text extraction, while `clean_text` and `normalize_text` standardize the content before chunking.

### Semantic Extraction and Graph Construction

Once parsed, text flows into `TextSplitter` for intelligent chunking. The chunks then pass through extractors in [`semantica/semantic_extract.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/semantic_extract.py):

- **NamedEntityRecognizer**: Identifies entities and types
- **RelationExtractor**: Discovers relationships between entities  
- **TripletExtractor**: Generates subject-predicate-object triplets

The `GraphBuilder` in [`semantica/kg.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg.py) assembles these into a knowledge graph, while `ConflictDetector` and `EntityResolver` handle deduplication and entity linking.

### Export and Visualization

Final outputs are serialized using exporters in [`semantica/export.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export.py). The `ParquetExporter` and `ArrowExporter` write optimized columnar files, while `RDFExporter` generates linked data formats. For interactive exploration, `KGVisualizer` renders the graph structure in your browser or notebook.

## Summary

- Install the core library with `pip install -e .` and add extras like `[export]` or `[vector]` for specific examples
- Run any example by executing `python examples/<script>.py` from the repository root
- Each script creates a temporary workspace, runs the full pipeline, and cleans up automatically
- The examples demonstrate production patterns: ingestion → parsing → chunking → extraction → graph building → reasoning → export
- Key modules include [`semantica/export.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export.py) for serialization, [`semantica/kg.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg.py) for graph operations, and [`semantica/reasoning.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/reasoning.py) for decision intelligence

## Frequently Asked Questions

### What dependencies are required to run the Parquet export example?

You need the `[export]` extras installed, which include `pyarrow` and `pandas`. Install them with `pip install -e ".[export]"`. Without these, the `export_parquet()` function in [`semantica/export.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export.py) will raise an import error when attempting to write the Apache Parquet file.

### Where does the capability gap example store its temporary files?

The [`capability_gap_context_graphs_example.py`](https://github.com/semantica-agi/semantica/blob/main/capability_gap_context_graphs_example.py) script uses Python's `tempfile.mkdtemp()` to create a unique temporary directory for each run. It prints the path at startup and automatically cleans up the workspace after completion, ensuring no persistent clutter remains on your filesystem.

### Can I run the examples without installing the optional extras?

Yes, but only basic examples that do not rely on external formats. The core ingestion, parsing, and graph construction examples will run with the base installation. However, any script calling `ParquetExporter`, `ArrowExporter`, or `KGVisualizer` requires their respective extras (`[export]` or `[visualization]`) to be installed.

### How do I visualize the knowledge graph output from an example?

Use the `KGVisualizer` class from [`semantica/visualization.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization.py). The capability gap example demonstrates this by calling visualization methods after graph construction. Ensure you have installed the `[visualization]` extras, then run the script and open the generated HTML or notebook output to explore nodes, edges, and community clusters interactively.