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

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:

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:

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) provides the simplest entry point. It demonstrates how to use export_parquet() from semantica/export.py to persist entities and relationships to columnar storage:

# 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:

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). 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
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
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
8. Export: Persists results using ParquetExporter or visualizes with KGVisualizer from semantica/visualization.py

Execute the full pipeline:

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:

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

The GraphBuilder in 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. 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 for serialization, semantica/kg.py for graph operations, and 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 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 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. 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.

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