# cagostino/npcpy architecture

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

- Interactive diagram: https://gitdiagram.com/cagostino/npcpy
- Repository: https://github.com/cagostino/npcpy

## Overview

##### Project type and purpose
- npcpy is a Python-based agent framework and CLI toolset (npcsh, guac, pti, spool, yap, npc) for building, running, and experimenting with AI “NPC” agents.
- It provides both a core library (data I/O, model inference, memory, agent mixing, SQL tooling, OS automation) and multiple command-line interfaces for different interactive modes.

##### File structure
- Top level:
- npcpy/ – the main Python package, subdivided into submodules (data, gen, memory, mix, modes, migrations, npc_team, sql, work)
- cli entrypoints (npcpy/main.py, npcpy/routes.py, setup.py)
- docs/, examples/ – usage guides, sample NPCs, pipelines
- data/, test_data/ – sample SQLite DB and raw files for data-loading
- tests/ – unit and integration tests
- configuration (Makefile, mkdocs.yml, .github workflows, .env.example)
- Patterns:
- Modular design: each concern in its own subpackage (data handling, LLM generation, memory, agent modes, SQL tools, OS/automation)
- CLI shells wrap into `npcpy.main` or `npcpy.modes.serve`
- Persistent storage via SQLite (migrations, memory/history)

##### Extract insights from the README
- Core interfaces:
- npcpy library for programmatic agent creation
- npcsh: agentic/bash shell replacement
- guac: REPL with pomodoro-style stages
- pti, spool, yap, wander: specialized REPL loops
- npc CLI: wrapper for shell commands
- Inference via LiteLLM to local or remote providers (Ollama, OpenAI, Anthropic, etc.)
- Data layer: loading PDF, CSV, images, text into agent memory/knowledge graph
- Tools: built-in “tools” for file editing, web search, SQL execution, system control

a. Frontend CLIs & shells (npcsh, npc, guac, pti, spool, yap)
b. Core library modules:
– Data layer (npcpy/data/*)
– Generation layer (npcpy/gen/* and llm_funcs.py)
– Memory & persistence (npcpy/memory/* + SQLite)
– Agentic mixing (npcpy/mix/*)
– Interaction modes (npcpy/modes/*)
– SQL tooling (npcpy/sql/*)
– OS/task automation (npcpy/work/*)
– Project/global NPC teams & tools (npcpy/npc_team & ./npc_team/)
c. External services & resources:
– LLM providers via LiteLLM (Ollama, OpenAI, etc.)
– Local SQLite database (history, migrations)
– File system (data files, .npcshrc, example pipelines)
– Optional: ffmpeg, portaudio, pyautogui for voice/screen tools

##### Relationships and interactions
- User → CLI/shell input → command parser in npcpy.main or modes
- Parser dispatches to one of the modes (agentic, conversational, direct bash, guac, pti, etc.)
- Mode uses core library:
- Data layer to load inputs
- Generation layer via llm_funcs and liteLLM adapter
- Memory layer to store/retrieve histories, knowledge graphs
- Mix layer to coordinate multiple agents if needed
- SQL layer for data-driven pipelines or store queries
- Work layer to run OS commands or GUI automation
- Library persists state to SQLite and may spawn subprocesses for shells or tools
- External LLM service calls over network or local daemon (Ollama)

##### Architectural patterns and design principles
- Separation of concerns: each functionality in its own subpackage
- Plug-and-play providers via a unified LiteLLM adapter interface
- Modular CLI fronts built on same core library
- Persistence/migrations layer decoupled from memory logic
- Extensibility: project-specific npc_team directory auto-discovered

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef frontend fill:#AED6F1,stroke:#2980B9,color:#1B4F72
    classDef core fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef proj fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef ext fill:#D5DBDB,stroke:#566573,color:#1C2833

    User["User"]:::ext

    subgraph "CLI Entry"
        Main["npcpy/main.py"]:::frontend
        Routes["npcpy/routes.py"]:::frontend
    end

    User --> Main
    Main --> Routes

    subgraph "Interaction Modes"
        NS["npcsh"]:::frontend
        N["npc"]:::frontend
        G["guac"]:::frontend
        P["pti"]:::frontend
        SP["spool"]:::frontend
        Y["yap"]:::frontend
        W["wander"]:::frontend
        SV["serve"]:::frontend
    end

    Routes --> NS
    Routes --> N
    Routes --> G
    Routes --> P
    Routes --> SP
    Routes --> Y
    Routes --> W
    Routes --> SV

    subgraph "Core Library"
        Data["npcpy/data"]:::core
        Gen["npcpy/gen"]:::core
        LLMFuncs["npcpy/llm_funcs.py"]:::core
        Memory["npcpy/memory"]:::core
        Migrations["npcpy/migrations"]:::core
        Mix["npcpy/mix"]:::core
        SQL["npcpy/sql"]:::core
        Work["npcpy/work"]:::core
        NPC["npcpy/npc_team"]:::proj
    end

    NS --> Data
    NS --> Gen
    NS --> Memory
    NS --> Mix
    NS --> SQL
    NS --> Work
    NS --> NPC

    N  --> Data
    G  --> Gen
    P  --> Memory
    SP --> SQL
    Y  --> Work
    W  --> Mix
    SV --> NPC

    Gen --> LLMFuncs
    Memory --> Migrations

    subgraph "External Services"
        LLM["LLM Providers (LiteLLM)"]:::ext
        DB[(SQLite DB)]:::ext
        FS["File System"]:::ext
        Tools["ffmpeg/portaudio/pyautogui"]:::ext
    end

    Gen --> LLM
    Memory --> DB
    SQL --> DB
    Data --> FS
    Work --> Tools

    click Main "https://github.com/cagostino/npcpy/blob/main/npcpy/main.py"
    click Routes "https://github.com/cagostino/npcpy/blob/main/npcpy/routes.py"
    click NS "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/npcsh.py"
    click N "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/npc.py"
    click G "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/guac.py"
    click P "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/pti.py"
    click SP "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/spool.py"
    click Y "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/yap.py"
    click W "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/wander.py"
    click SV "https://github.com/cagostino/npcpy/blob/main/npcpy/modes/serve.py"
    click Data "https://github.com/cagostino/npcpy/tree/main/npcpy/data/"
    click Gen "https://github.com/cagostino/npcpy/tree/main/npcpy/gen/"
    click LLMFuncs "https://github.com/cagostino/npcpy/blob/main/npcpy/llm_funcs.py"
    click Memory "https://github.com/cagostino/npcpy/tree/main/npcpy/memory/"
    click Migrations "https://github.com/cagostino/npcpy/tree/main/npcpy/migrations/"
    click Mix "https://github.com/cagostino/npcpy/tree/main/npcpy/mix/"
    click SQL "https://github.com/cagostino/npcpy/tree/main/npcpy/sql/"
    click Work "https://github.com/cagostino/npcpy/tree/main/npcpy/work/"
    click NPC "https://github.com/cagostino/npcpy/tree/main/npcpy/npc_team/"
    click setup "https://github.com/cagostino/npcpy/blob/main/setup.py"

    class Main,Routes,NS,N,G,P,SP,Y,W,SV frontend
    class Data,Gen,LLMFuncs,Memory,Migrations,Mix,SQL,Work core
    class NPC proj
    class User,LLM,DB,FS,Tools ext
```
