# pcfpcfpcf/straw architecture

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

- Interactive diagram: https://gitdiagram.com/pcfpcfpcf/straw
- Repository: https://github.com/pcfpcfpcf/straw

## Overview

Straw is a FastAPI harness for domain-specific reasoning agents, with a stated aim of enabling models to learn continuously. Its visible workflow accepts an authenticated agent request, optionally loads and compacts chat history, runs an agent against an external model API, and streams reasoning events while persisting the final messages. The harness also exposes reducer, misc-function, and direct-tool endpoints. The README describes broader learning ambitions, but the excerpts do not show a learning or model-training subsystem, nor concrete domain tool implementations.

Main entry points: [`core/domain.py`](https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py) (Authenticated API), [`core/agent.py`](https://github.com/pcfpcfpcf/straw/blob/master/core/agent.py) (Agent loop), [`core/chats.py`](https://github.com/pcfpcfpcf/straw/blob/master/core/chats.py) (Chat history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Harness API"]
  node_domain_api["Authenticated API<br/>[domain.py]"]
  node_reducers["Reducers<br/>[domain.py]"]
  node_misc["Misc functions<br/>[domain.py]"]
  node_tool_endpoint["Direct tool route<br/>[domain.py]"]
end

subgraph group_reasoning["Agent Runtime"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_tool_schema["Tool definitions<br/>[types.py]"]
  node_tool_exec["Tool executor<br/>[agent.py]"]
end

subgraph group_state["Conversation State"]
  node_chat_service["Chat history<br/>[chats.py]"]
  node_chat_db[("SQLite chat store<br/>[chats.py]")]
end

node_caller(("API caller"))
node_model_api{{"Model API"}}

node_caller -->|"sends requests"| node_domain_api
node_domain_api -->|"dispatches reduce"| node_reducers
node_domain_api -->|"dispatches misc"| node_misc
node_domain_api -->|"routes tools"| node_tool_endpoint
node_domain_api -->|"runs agent"| node_agent
node_domain_api -->|"loads and appends"| node_chat_service
node_domain_api -->|"executes direct tool"| node_tool_exec
node_agent -->|"calls model"| node_model_api
node_chat_service -->|"reads and writes"| node_chat_db

click node_domain_api "https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py"
click node_reducers "https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py"
click node_misc "https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py"
click node_tool_endpoint "https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py"
click node_agent "https://github.com/pcfpcfpcf/straw/blob/master/core/agent.py"
click node_tool_schema "https://github.com/pcfpcfpcf/straw/blob/master/core/types.py"
click node_tool_exec "https://github.com/pcfpcfpcf/straw/blob/master/core/agent.py"
click node_chat_service "https://github.com/pcfpcfpcf/straw/blob/master/core/chats.py"
click node_chat_db "https://github.com/pcfpcfpcf/straw/blob/master/core/chats.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_domain_api,node_reducers,node_misc,node_tool_endpoint toneBlue
class node_agent,node_tool_schema,node_tool_exec toneAmber
class node_chat_service,node_chat_db,node_caller,node_model_api toneMint
```

## Components

### Harness API

- [Authenticated API](https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py): `core/domain.py`
- [Reducers](https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py): `core/domain.py`
- [Misc functions](https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py): `core/domain.py`
- [Direct tool route](https://github.com/pcfpcfpcf/straw/blob/master/core/domain.py): `core/domain.py`

### Agent Runtime

- [Agent loop](https://github.com/pcfpcfpcf/straw/blob/master/core/agent.py): `core/agent.py`
- [Tool definitions](https://github.com/pcfpcfpcf/straw/blob/master/core/types.py): `core/types.py`
- [Tool executor](https://github.com/pcfpcfpcf/straw/blob/master/core/agent.py): `core/agent.py`

### Conversation State

- [Chat history](https://github.com/pcfpcfpcf/straw/blob/master/core/chats.py): `core/chats.py`
- [SQLite chat store](https://github.com/pcfpcfpcf/straw/blob/master/core/chats.py): `core/chats.py`

### Other components

- **API caller**
- **Model API**

## Connections

- API caller → Authenticated API: sends requests (evidence: `core/domain.py`)
- Authenticated API → Reducers: dispatches reduce (evidence: `core/domain.py`)
- Authenticated API → Misc functions: dispatches misc (evidence: `core/domain.py`)
- Authenticated API → Direct tool route: routes tools (evidence: `core/domain.py`)
- Authenticated API → Agent loop: runs agent (evidence: `core/domain.py`)
- Authenticated API → Chat history: loads and appends (evidence: `core/domain.py`)
- Authenticated API → Tool executor: executes direct tool (evidence: `core/domain.py`)
- Agent loop → Model API: calls model (evidence: `core/agent.py`)
- Chat history → SQLite chat store: reads and writes (evidence: `core/chats.py`)
