# thetrebor/pi-reasonix architecture

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

- Interactive diagram: https://gitdiagram.com/thetrebor/pi-reasonix
- Repository: https://github.com/thetrebor/pi-reasonix

## Overview

pi-reasonix is a Pi extension that activates for DeepSeek models. Its main workflow modifies provider requests to stabilize cache prefixes and compact oversized tool results, then processes responses to collect cache metrics and repair malformed or repeated tool calls. A status command exposes session statistics. The shared types module is included as an internal layer. Edges reflect the extension excerpt or README; unsampled integrations are not expanded beyond documented behavior.

Main entry points: [`extensions/index.ts`](https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts) (Extension hooks), [`src/cache-first.ts`](https://github.com/thetrebor/pi-reasonix/blob/main/src/cache-first.ts) (Prefix guard), [`src/repair.ts`](https://github.com/thetrebor/pi-reasonix/blob/main/src/repair.ts) (Tool-call repair), [`src/cost-control.ts`](https://github.com/thetrebor/pi-reasonix/blob/main/src/cost-control.ts) (Result compaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Pi integration"]
  node_pi_host["Pi host"]
  node_extension["Extension hooks<br/>[index.ts]"]
  node_model_detection["Model detection<br/>[index.ts]"]
  node_status["Status command<br/>[index.ts]"]
  node_shared_types["Shared types<br/>[types.ts]"]
end

subgraph group_cache["Cache stability"]
  node_prefix_guard["Prefix guard<br/>[cache-first.ts]"]
  node_append_log["Append-only check<br/>[cache-first.ts]"]
end

subgraph group_repair["Tool-call repair"]
  node_tool_repair["Tool-call repair<br/>[repair.ts]"]
end

subgraph group_cost_metrics["Cost and metrics"]
  node_result_compaction["Result compaction<br/>[cost-control.ts]"]
  node_context_usage["Context usage<br/>[cost-control.ts]"]
  node_cache_metrics["Cache metrics<br/>[index.ts]"]
end

node_user(("Pi user"))
node_deepseek_api["DeepSeek API"]

node_pi_host -->|"fires hooks"| node_extension
node_extension -->|"detects model"| node_model_detection
node_model_detection -->|"sets session"| node_extension
node_extension -->|"stabilizes prefix"| node_prefix_guard
node_extension -->|"checks history"| node_append_log
node_extension -->|"compacts results"| node_result_compaction
node_extension -->|"estimates tokens"| node_context_usage
node_extension -->|"repairs calls"| node_tool_repair
node_extension -->|"collects metrics"| node_cache_metrics
node_extension -->|"sends modified request"| node_deepseek_api
node_deepseek_api -->|"returns response"| node_pi_host
node_user -->|"requests status"| node_status
node_status -->|"shows statistics"| node_user

click node_extension "https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts"
click node_model_detection "https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts"
click node_status "https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts"
click node_prefix_guard "https://github.com/thetrebor/pi-reasonix/blob/main/src/cache-first.ts"
click node_append_log "https://github.com/thetrebor/pi-reasonix/blob/main/src/cache-first.ts"
click node_tool_repair "https://github.com/thetrebor/pi-reasonix/blob/main/src/repair.ts"
click node_result_compaction "https://github.com/thetrebor/pi-reasonix/blob/main/src/cost-control.ts"
click node_context_usage "https://github.com/thetrebor/pi-reasonix/blob/main/src/cost-control.ts"
click node_cache_metrics "https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts"
click node_shared_types "https://github.com/thetrebor/pi-reasonix/blob/main/src/types.ts"

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_pi_host,node_extension,node_model_detection,node_status,node_shared_types,node_user toneBlue
class node_prefix_guard,node_append_log toneAmber
class node_tool_repair,node_deepseek_api toneMint
class node_result_compaction,node_context_usage,node_cache_metrics toneRose
```

## Components

### Pi integration

- **Pi host**
- [Extension hooks](https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts): `extensions/index.ts`
- [Model detection](https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts): `extensions/index.ts`
- [Status command](https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts): `extensions/index.ts`
- [Shared types](https://github.com/thetrebor/pi-reasonix/blob/main/src/types.ts): `src/types.ts`

### Cache stability

- [Prefix guard](https://github.com/thetrebor/pi-reasonix/blob/main/src/cache-first.ts): `src/cache-first.ts`
- [Append-only check](https://github.com/thetrebor/pi-reasonix/blob/main/src/cache-first.ts): `src/cache-first.ts`

### Tool-call repair

- [Tool-call repair](https://github.com/thetrebor/pi-reasonix/blob/main/src/repair.ts): `src/repair.ts`

### Cost and metrics

- [Result compaction](https://github.com/thetrebor/pi-reasonix/blob/main/src/cost-control.ts): `src/cost-control.ts`
- [Context usage](https://github.com/thetrebor/pi-reasonix/blob/main/src/cost-control.ts): `src/cost-control.ts`
- [Cache metrics](https://github.com/thetrebor/pi-reasonix/blob/main/extensions/index.ts): `extensions/index.ts`

### Other components

- **Pi user**
- **DeepSeek API**

## Connections

- Pi host → Extension hooks: fires hooks (evidence: `README.md`)
- Extension hooks → Model detection: detects model (evidence: `extensions/index.ts`)
- Model detection → Extension hooks: sets session (evidence: `extensions/index.ts`)
- Extension hooks → Prefix guard: stabilizes prefix (evidence: `extensions/index.ts`)
- Extension hooks → Append-only check: checks history (evidence: `extensions/index.ts`)
- Extension hooks → Result compaction: compacts results (evidence: `extensions/index.ts`)
- Extension hooks → Context usage: estimates tokens (evidence: `extensions/index.ts`)
- Extension hooks → Tool-call repair: repairs calls (evidence: `extensions/index.ts`)
- Extension hooks → Cache metrics: collects metrics (evidence: `extensions/index.ts`)
- Extension hooks → DeepSeek API: sends modified request (evidence: `README.md`)
- DeepSeek API → Pi host: returns response (evidence: `README.md`)
- Pi user → Status command: requests status (evidence: `README.md`)
- Status command → Pi user: shows statistics (evidence: `README.md`)
