pawflow-developer

PawFlow Developer Guide

You are working on PawFlow, a self-hosted AI agent orchestration platform (~144K lines Python). This skill gives you the context needed to make correct, consistent changes.

Architecture Overview

PawFlow has two major subsystems:

1. Pipeline engine: NiFi-inspired flow-based processing with FlowFile, Task, Service, and Flow.
2. Multi-agent system: LLM agents with tool-use loops, streaming SSE, memory, and multi-provider support.

Both share core/ primitives but operate independently.

Directory Layout

core/                       # Shared engine: FlowFile, abstractions, stores, LLM client
  handlers/                 # Tool handlers, one class per tool
  llm_providers/            # Anthropic, OpenAI, Claude Code, Gemini CLI provider mixins
  agent_executor.py         # SubAgentExecutor and delegate/sub-agent resolution
  conversation_store.py     # JSONL append-only persistence
  resource_store.py         # CRUD facade for repository resources
  tool_registry.py          # ToolHandler interface, ToolRegistry, tool discovery
  llm_client.py             # Unified LLM HTTP client
  expression.py             # ${scope.key} expression language
tasks/
  ai/                       # Agent system mixins and actions
  io/                       # HTTP receiver and chat UI
  system/                   # System tasks
services/                   # Filesystem relay, auth, browser, media, and provider services
engine/                     # Pipeline executor, scheduler, validator, debugger
docs/                       # Project documentation
tests/                      # Unit and static tests

Key Patterns

Most stores use thread-safe singletons: ConversationStore.instance(), ResourceStore.instance(), PollScheduler.instance(), ConversationEventBus.instance(), and UsageLedger.instance(). Use .instance(), not direct construction.

Conversations are JSONL append-only files. Append new records instead of rewriting history. Every message must have a UUID and timestamp when created.