How cagostino/npcpy works
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