# goodmanbrio/wsdknpsoas architecture

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

- Interactive diagram: https://gitdiagram.com/goodmanbrio/wsdknpsoas
- Repository: https://github.com/goodmanbrio/wsdknpsoas
- Video tour (about a minute): https://gitdiagram.com/goodmanbrio/wsdknpsoas/video

## Overview

PSOAS is an interactive LLM-orchestrated financial research and charting application. A user query enters the harness, which dispatches tools; the main documented workflow designs financial-data stencils, extracts and computes values from ingested company documents, then optionally plans and renders charts. Separate branches provide general research and a legacy PMS1 pipeline. The graph follows the README for PMS2 orchestration; several implementation details, including storage wiring and research internals, were not sampled, so uncertain links are omitted.

Main entry points: [`src/harness/execute_tool.py`](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/execute_tool.py) (Tool Dispatcher), [`src/scripts/PMS2/pms2.py`](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/pms2.py) (PMS2 Pipeline), [`src/harness/agent_loop.py`](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/agent_loop.py) (Agent Loop), [`src/scripts/PMS2/dispatcher.py`](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/dispatcher.py) (Firm Dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Orchestration"]
  node_entry["CLI Entry<br/>[psoas.py]"]
  node_agent["Agent Loop<br/>[agent_loop.py]"]
  node_dispatch["Tool Dispatcher<br/>[execute_tool.py]"]
  node_registry[("Opaque Registry<br/>[opaque_registry.py]")]
  node_terminal["Terminal Router<br/>[terminal_router.py]"]
  node_llm["LLM Backend<br/>[llm.py]"]
end

subgraph group_pms2["PMS2 Extraction"]
  node_pms2["PMS2 Pipeline<br/>[pms2.py]"]
  node_sekei["Stencil Design<br/>[sekei_loop.py]"]
  node_mapper["File Discovery<br/>[mapper.py]"]
  node_dispatcher["Firm Dispatcher<br/>[dispatcher.py]"]
  node_planner["Batch Planner<br/>[batch_planner.py]"]
  node_extractor["Chunk Extraction<br/>[leng_caller.py]"]
  node_validator["Chunk Validation<br/>[validator_loop.py]"]
  node_merge["Merge and Compute<br/>[merge_compute.py]"]
end

subgraph group_documents["Document Preparation"]
  node_ingest["Document Ingest<br/>[00_Ingest.py]"]
  node_chunk["Document Chunking<br/>[01_Chunk.py]"]
end

subgraph group_charts["Charting"]
  node_pteca["Chart Planner<br/>[tool_pteca.py]"]
  node_renderer["Chart Renderer<br/>[stencil2chart.py]"]
end

subgraph group_other["Other Tools"]
  node_research["Research Pipeline"]
  node_pms1["Legacy PMS1<br/>[tool_pms1.py]"]
  node_index[("PMS1 Index Store<br/>[index_store.py]")]
end

node_user(("User"))
node_documents_in["Financial Documents"]
node_chart_service["Chart Output"]

node_user -->|"submits query"| node_entry
node_entry -->|"starts"| node_agent
node_agent -->|"requests decisions"| node_llm
node_agent -->|"dispatches tools"| node_dispatch
node_dispatch -->|"stores results"| node_registry
node_agent -->|"routes interaction"| node_terminal
node_dispatch -->|"runs extraction"| node_pms2
node_pms2 -->|"designs stencils"| node_sekei
node_pms2 -->|"discovers files"| node_mapper
node_pms2 -->|"dispatches firms"| node_dispatcher
node_dispatcher -->|"plans batches"| node_planner
node_dispatcher -->|"extracts chunks"| node_extractor
node_extractor -->|"validates chunks"| node_validator
node_pms2 -->|"merges and computes"| node_merge
node_documents_in -->|"converts documents"| node_ingest
node_ingest -->|"provides markdown"| node_chunk
node_dispatch -->|"plans charts"| node_pteca
node_pteca -->|"requests chart choices"| node_llm
node_dispatch -->|"renders chart"| node_renderer
node_renderer -->|"produces chart"| node_chart_service
node_dispatch -->|"runs research"| node_research
node_dispatch -.->|"runs legacy pipeline"| node_pms1
node_pms1 -.->|"loads index"| node_index

click node_entry "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/psoas.py"
click node_agent "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/agent_loop.py"
click node_dispatch "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/execute_tool.py"
click node_registry "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/opaque_registry.py"
click node_terminal "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/terminal_router.py"
click node_llm "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/llm.py"
click node_pms2 "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/pms2.py"
click node_sekei "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/sekei_loop.py"
click node_mapper "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/mapper.py"
click node_dispatcher "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/dispatcher.py"
click node_planner "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/batch_planner.py"
click node_extractor "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/leng_caller.py"
click node_validator "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/validator_loop.py"
click node_merge "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/merge_compute.py"
click node_ingest "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/00_Ingest.py"
click node_chunk "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/01_Chunk.py"
click node_pteca "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/tools/tool_pteca.py"
click node_renderer "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/stencil2chart.py"
click node_research "https://github.com/goodmanbrio/wsdknpsoas/tree/main/src/scripts/research"
click node_pms1 "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/tools/tool_pms1.py"
click node_index "https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/Poony_Multiretrieval_S1/src/index_store.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_entry,node_agent,node_dispatch,node_registry,node_terminal,node_llm,node_user toneBlue
class node_pms2,node_sekei,node_mapper,node_dispatcher,node_planner,node_extractor,node_validator,node_merge toneAmber
class node_ingest,node_chunk toneMint
class node_pteca,node_renderer toneRose
class node_research,node_pms1,node_index,node_documents_in,node_chart_service toneIndigo
```

## Components

### Orchestration

- [CLI Entry](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/psoas.py): `src/psoas.py`
- [Agent Loop](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/agent_loop.py): `src/harness/agent_loop.py`
- [Tool Dispatcher](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/execute_tool.py): `src/harness/execute_tool.py`
- [Opaque Registry](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/opaque_registry.py): `src/harness/opaque_registry.py`
- [Terminal Router](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/harness/terminal_router.py): `src/harness/terminal_router.py`
- [LLM Backend](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/llm.py): `src/scripts/llm.py`

### PMS2 Extraction

- [PMS2 Pipeline](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/pms2.py): `src/scripts/PMS2/pms2.py`
- [Stencil Design](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/sekei_loop.py): `src/scripts/PMS2/sekei_loop.py`
- [File Discovery](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/mapper.py): `src/scripts/PMS2/mapper.py`
- [Firm Dispatcher](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/dispatcher.py): `src/scripts/PMS2/dispatcher.py`
- [Batch Planner](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/batch_planner.py): `src/scripts/PMS2/batch_planner.py`
- [Chunk Extraction](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/leng_caller.py): `src/scripts/PMS2/leng_caller.py`
- [Chunk Validation](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/validator_loop.py): `src/scripts/PMS2/validator_loop.py`
- [Merge and Compute](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/merge_compute.py): `src/scripts/PMS2/merge_compute.py`

### Document Preparation

- [Document Ingest](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/00_Ingest.py): `src/scripts/PMS2/00_Ingest.py`
- [Document Chunking](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/PMS2/01_Chunk.py): `src/scripts/PMS2/01_Chunk.py`

### Charting

- [Chart Planner](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/tools/tool_pteca.py): `src/tools/tool_pteca.py`
- [Chart Renderer](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/stencil2chart.py): `src/scripts/stencil2chart.py`

### Other Tools

- [Research Pipeline](https://github.com/goodmanbrio/wsdknpsoas/tree/main/src/scripts/research): `src/scripts/research`
- [Legacy PMS1](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/tools/tool_pms1.py): `src/tools/tool_pms1.py`
- [PMS1 Index Store](https://github.com/goodmanbrio/wsdknpsoas/blob/main/src/scripts/Poony_Multiretrieval_S1/src/index_store.py): `src/scripts/Poony_Multiretrieval_S1/src/index_store.py`

### Other components

- **User**
- **Financial Documents**
- **Chart Output**

## Connections

- User → CLI Entry: submits query
- CLI Entry → Agent Loop: starts
- Agent Loop → LLM Backend: requests decisions
- Agent Loop → Tool Dispatcher: dispatches tools
- Tool Dispatcher → Opaque Registry: stores results
- Agent Loop → Terminal Router: routes interaction
- Tool Dispatcher → PMS2 Pipeline: runs extraction
- PMS2 Pipeline → Stencil Design: designs stencils
- PMS2 Pipeline → File Discovery: discovers files
- PMS2 Pipeline → Firm Dispatcher: dispatches firms
- Firm Dispatcher → Batch Planner: plans batches
- Firm Dispatcher → Chunk Extraction: extracts chunks
- Chunk Extraction → Chunk Validation: validates chunks
- PMS2 Pipeline → Merge and Compute: merges and computes
- Financial Documents → Document Ingest: converts documents
- Document Ingest → Document Chunking: provides markdown
- Tool Dispatcher → Chart Planner: plans charts
- Chart Planner → LLM Backend: requests chart choices
- Tool Dispatcher → Chart Renderer: renders chart
- Chart Renderer → Chart Output: produces chart
- Tool Dispatcher → Research Pipeline: runs research
- Tool Dispatcher → Legacy PMS1: runs legacy pipeline
- Legacy PMS1 → PMS1 Index Store: loads index