# fartlabs/turtle-agent architecture

> Architecture diagram of the GitHub repository fartlabs/turtle-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fartlabs/turtle-agent
- Repository: https://github.com/fartlabs/turtle-agent

## Overview

##### Project type and purpose
- This is a Deno-based, modular CLI/library “turtle-agent” for generating, disambiguating, linking, storing, and searching RDF/Turtle knowledge graphs from natural-language input. It’s an open-source pipeline tool rather than a web application.

##### File structure
- Top-level: deno.json (Deno config), README.md, .vscode.
- src/ dissects into six primary domains:
- ner/ – named-entity recognition interface and implementation
- disambiguator/ – entity disambiguation logic plus a CLI entrypoint
- linker/ – linking recognized/disambiguated entities to knowledge bases
- generator/ – context setup, prompt formatting, and graph generation modules
- n3store/ – in-memory/Turtle store with persistence plugins (FS, KV) and SHACL validation, plus interceptor middleware (count, debug, error, Orama sync)
- search/ – full-text (Orama) and SPARQL search adapters, with their own persist and triple-store integrations
- Test files sit alongside their implementations.

##### README for additional insights
- Purpose statement: “Generate knowledge graphs with natural language.”
- Deno tasks for test and lint hint at a CI pipeline but no deployment files.

a. Main components
- Front-end/CLI: user interface for submitting text (e.g., disambiguator CLI or direct library calls)
- NER Engine: extracts raw entities from text
- Disambiguator: refines entity mentions to canonical identifiers
- Linker: binds entities to external KBs/URIs
- Generator: builds RDF triples using few-shot contexts and formatting rules
- N3 Store: holds triples, applies SHACL validation, persists to FS or KV, and fires interceptors
- Search Layer: supports full-text (Orama) and SPARQL queries against the stored graph
- Configuration/Infra: Deno runtime, deno.json, persistence backends (FS, KV), and test harnesses
b. Relationships and interactions
1. User → CLI/Library API
2. CLI/API calls NER → outputs entity spans
3. Output → Disambiguator → IDs
4. IDs → Linker → external URIs
5. URIs + context → Generator → RDF triples
6. Triples → N3Store → interceptors → persistence
7. End user or other clients → Search Layer → fetch via Orama or SPARQL
c. Architectural patterns and principles
- Modular pipeline: each major concern lives in its own directory with clear inputs/outputs
- Middleware/interceptor pattern in n3store for cross-cutting concerns (counting, logging, error handling, sync)
- Adapter pattern in search (Orama adapter vs. SPARQL adapter) and persistence (FS vs. KV)
- Few-shot prompt contexts for pluggable generator strategies
d. Key technologies/frameworks
- Deno + TypeScript
- Orama (full-text search engine)
- SHACL for schema validation
- Simple file system and key-value persistence layers
- Potential external LLM service (via generator context)

##### Detail without overthinking
- With its primary responsibility and any sub-modules (e.g., interceptor types)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / Library
    subgraph "CLI / Library"
        CLI["CLI / Library API"]:::cli
    end

    %% NLP Components
    subgraph "NLP Components"
        NER["NER Engine"]:::nlp
        Disamb["Disambiguator"]:::nlp
        Linker["Linker"]:::nlp
    end

    %% Generator
    subgraph "Generator"
        Gen["Generator"]:::gen
    end

    %% N3 Store with Interceptors, Persistence, SHACL
    subgraph "N3 Store (with Interceptors)"
        Store["N3 Store"]:::storage
        subgraph "Interceptors"
            CountInt["Count Interceptor"]:::storage
            DebugInt["Debug Interceptor"]:::storage
            ErrorInt["Error Interceptor"]:::storage
            OramaInt["Orama Sync Interceptor"]:::storage
        end
        subgraph "Persistence Adapters"
            FS["FS Adapter"]:::storage
            KV["KV Adapter"]:::storage
        end
        subgraph "SHACL Validation"
            Validate["SHACL Validate"]:::storage
        end
    end

    %% Search Layer
    subgraph "Search Layer"
        Orama["Orama Adapter"]:::storage
        SPARQL["SPARQL Adapter"]:::storage
    end

    %% Configuration
    subgraph "Configuration"
        Config["deno.json / README.md"]:::config
    end

    %% Data Flow
    CLI -->|"submit text"| NER
    NER -->|"entity spans"| Disamb
    Disamb -->|"canonical IDs"| Linker
    Linker -->|"external URIs"| Gen
    Gen -->|"RDF triples"| Store
    Store -->|"persist & intercept"| FS
    Store --> FS
    Store --> KV
    Store --> Validate
    FS --> CountInt
    FS --> DebugInt
    FS --> ErrorInt
    FS --> OramaInt
    Store --> Orama
    Store --> SPARQL
    Config --> CLI

    %% Search Queries
    Orama -->|"full-text search"| Store
    SPARQL -->|"SPARQL queries"| Store

    %% Click Events
    click NER "https://github.com/fartlabs/turtle-agent/blob/main/src/ner/ner-interface.ts"
    click Disamb "https://github.com/fartlabs/turtle-agent/blob/main/src/disambiguator/disambiguator.ts"
    click CLI "https://github.com/fartlabs/turtle-agent/blob/main/src/disambiguator/cli/disambiguator.ts"
    click Linker "https://github.com/fartlabs/turtle-agent/blob/main/src/linker/entity-linker.ts"
    click Gen "https://github.com/fartlabs/turtle-agent/blob/main/src/generator/generator.ts"
    click Store "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/custom-n3store.ts"
    click CountInt "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/interceptors/count-interceptor.ts"
    click DebugInt "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/interceptors/debug-interceptor.ts"
    click ErrorInt "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/interceptors/error-interceptor.ts"
    click OramaInt "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/interceptors/orama-sync-interceptor.ts"
    click FS "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/persist/fs.ts"
    click KV "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/persist/kv.ts"
    click Validate "https://github.com/fartlabs/turtle-agent/blob/main/src/n3store/shacl/validate.ts"
    click Orama "https://github.com/fartlabs/turtle-agent/blob/main/src/search/orama/search.ts"
    click SPARQL "https://github.com/fartlabs/turtle-agent/blob/main/src/search/sparql/search.ts"
    click Config "https://github.com/fartlabs/turtle-agent/blob/main/deno.json"

    %% Styles
    classDef nlp fill:#a8f0c6,stroke:#065f46
    classDef gen fill:#ffd8a8,stroke:#b45309
    classDef storage fill:#a8c2ff,stroke:#1e3a8a
    classDef cli fill:#e2e8f0,stroke:#475569
    classDef config fill:#f3f4f6,stroke:#6b7280
```
