# bennyjo/phil architecture

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

- Interactive diagram: https://gitdiagram.com/bennyjo/phil
- Repository: https://github.com/bennyjo/phil

## Overview

Phil is an AI prediction-market trader whose paper cycles discover and screen markets, research candidates, record forecasts, and place simulated bets; resolutions then feed calibration and retrospectives that inform strategy changes. A separately enabled real-money path twins eligible paper bets through Pearl Connect under operator-controlled caps. The README documents the hourly, watcher, and daily-retrospective roles; only selected source excerpts were available, so uncertain internal call wiring is omitted.

Main entry points: [`core/real.py`](https://github.com/bennyjo/phil/blob/main/core/real.py) (Real execution), [`core/scan.py`](https://github.com/bennyjo/phil/blob/main/core/scan.py) (Market discovery), [`journal/ledger.jsonl`](https://github.com/bennyjo/phil/blob/main/journal/ledger.jsonl) (Paper ledger), [`loop.sh`](https://github.com/bennyjo/phil/blob/main/loop.sh) (Cycle launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cycle["Trading cycle"]
  node_loop["Cycle launcher<br/>[loop.sh]"]
  node_watch["Market watchers<br/>[watch.py]"]
  node_scan["Market discovery<br/>[scan.py]"]
  node_screen["Market screening<br/>[screen.py]"]
end

subgraph group_strategy["Strategy and research"]
  node_discovery["Discovery queries<br/>[discovery.py]"]
  node_playbook["Trading playbook<br/>[playbook.md]"]
  node_research_tools["Research tools"]
  node_policy["Betting policy<br/>[policy.py]"]
  node_proposals["Operator proposals<br/>[proposals.md]"]
end

subgraph group_evidence["Evidence and learning"]
  node_forecasts[("Forecast journal<br/>[forecasts.jsonl]")]
  node_resolve["Outcome resolution<br/>[resolve.py]"]
  node_score["Calibration scoring<br/>[score.py]"]
  node_retro["Daily retrospectives"]
end

subgraph group_execution["Trade execution"]
  node_ledger[("Paper ledger<br/>[ledger.jsonl]")]
  node_real["Real execution<br/>[real.py]"]
  node_protected["Execution caps<br/>[protected.json]"]
end

node_operator(("Human operator"))
node_claude(("Claude Code agent"))
node_polymarket["Polymarket"]
node_pearl["Pearl Connect"]

node_operator -->|"starts cycles"| node_loop
node_loop -->|"launches agent"| node_claude
node_claude -->|"runs discovery"| node_scan
node_scan -->|"gets queries"| node_discovery
node_scan -->|"fetches markets"| node_polymarket
node_scan -->|"passes markets"| node_screen
node_claude -->|"screens markets"| node_screen
node_claude -->|"uses guidance"| node_playbook
node_claude -->|"uses research"| node_research_tools
node_claude -->|"records beliefs"| node_forecasts
node_claude -->|"chooses bets"| node_policy
node_policy -->|"records paper bets"| node_ledger
node_resolve -->|"checks resolutions"| node_polymarket
node_resolve -->|"settles positions"| node_ledger
node_score -->|"reads results"| node_ledger
node_score -->|"scores forecasts"| node_forecasts
node_claude -->|"writes retrospectives"| node_retro
node_retro -->|"informs revisions"| node_playbook
node_claude -->|"requests changes"| node_proposals
node_operator -->|"reviews requests"| node_proposals
node_watch -->|"checks listings"| node_polymarket
node_watch -->|"triggers cycles"| node_loop
node_real -->|"reads caps"| node_protected
node_real -->|"places orders"| node_polymarket
node_real -->|"requests signatures"| node_pearl
node_operator -.->|"enables real mode"| node_real
node_real -->|"records fills"| node_ledger

click node_loop "https://github.com/bennyjo/phil/blob/main/loop.sh"
click node_watch "https://github.com/bennyjo/phil/blob/main/core/watch.py"
click node_scan "https://github.com/bennyjo/phil/blob/main/core/scan.py"
click node_discovery "https://github.com/bennyjo/phil/blob/main/strategy/discovery.py"
click node_screen "https://github.com/bennyjo/phil/blob/main/core/screen.py"
click node_playbook "https://github.com/bennyjo/phil/blob/main/strategy/playbook.md"
click node_research_tools "https://github.com/bennyjo/phil/tree/main/strategy/tools"
click node_policy "https://github.com/bennyjo/phil/blob/main/strategy/policy.py"
click node_forecasts "https://github.com/bennyjo/phil/blob/main/journal/forecasts.jsonl"
click node_ledger "https://github.com/bennyjo/phil/blob/main/journal/ledger.jsonl"
click node_resolve "https://github.com/bennyjo/phil/blob/main/core/resolve.py"
click node_score "https://github.com/bennyjo/phil/blob/main/core/score.py"
click node_retro "https://github.com/bennyjo/phil/tree/main/journal/retros"
click node_proposals "https://github.com/bennyjo/phil/blob/main/journal/proposals.md"
click node_real "https://github.com/bennyjo/phil/blob/main/core/real.py"
click node_protected "https://github.com/bennyjo/phil/blob/main/config/protected.json"

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_loop,node_watch,node_scan,node_screen toneBlue
class node_discovery,node_playbook,node_research_tools,node_policy,node_proposals toneAmber
class node_forecasts,node_resolve,node_score,node_retro toneMint
class node_ledger,node_real,node_protected toneRose
class node_operator,node_claude,node_polymarket,node_pearl toneIndigo
```

## Components

### Trading cycle

- [Cycle launcher](https://github.com/bennyjo/phil/blob/main/loop.sh): `loop.sh`
- [Market watchers](https://github.com/bennyjo/phil/blob/main/core/watch.py): `core/watch.py`
- [Market discovery](https://github.com/bennyjo/phil/blob/main/core/scan.py): `core/scan.py`
- [Market screening](https://github.com/bennyjo/phil/blob/main/core/screen.py): `core/screen.py`

### Strategy and research

- [Discovery queries](https://github.com/bennyjo/phil/blob/main/strategy/discovery.py): `strategy/discovery.py`
- [Trading playbook](https://github.com/bennyjo/phil/blob/main/strategy/playbook.md): `strategy/playbook.md`
- [Research tools](https://github.com/bennyjo/phil/tree/main/strategy/tools): `strategy/tools`
- [Betting policy](https://github.com/bennyjo/phil/blob/main/strategy/policy.py): `strategy/policy.py`
- [Operator proposals](https://github.com/bennyjo/phil/blob/main/journal/proposals.md): `journal/proposals.md`

### Evidence and learning

- [Forecast journal](https://github.com/bennyjo/phil/blob/main/journal/forecasts.jsonl): `journal/forecasts.jsonl`
- [Outcome resolution](https://github.com/bennyjo/phil/blob/main/core/resolve.py): `core/resolve.py`
- [Calibration scoring](https://github.com/bennyjo/phil/blob/main/core/score.py): `core/score.py`
- [Daily retrospectives](https://github.com/bennyjo/phil/tree/main/journal/retros): `journal/retros`

### Trade execution

- [Paper ledger](https://github.com/bennyjo/phil/blob/main/journal/ledger.jsonl): `journal/ledger.jsonl`
- [Real execution](https://github.com/bennyjo/phil/blob/main/core/real.py): `core/real.py`
- [Execution caps](https://github.com/bennyjo/phil/blob/main/config/protected.json): `config/protected.json`

### Other components

- **Human operator**
- **Claude Code agent**
- **Polymarket**
- **Pearl Connect**

## Connections

- Human operator → Cycle launcher: starts cycles
- Cycle launcher → Claude Code agent: launches agent
- Claude Code agent → Market discovery: runs discovery
- Market discovery → Discovery queries: gets queries
- Market discovery → Polymarket: fetches markets
- Market discovery → Market screening: passes markets
- Claude Code agent → Market screening: screens markets
- Claude Code agent → Trading playbook: uses guidance
- Claude Code agent → Research tools: uses research
- Claude Code agent → Forecast journal: records beliefs
- Claude Code agent → Betting policy: chooses bets
- Betting policy → Paper ledger: records paper bets
- Outcome resolution → Polymarket: checks resolutions
- Outcome resolution → Paper ledger: settles positions
- Calibration scoring → Paper ledger: reads results
- Calibration scoring → Forecast journal: scores forecasts
- Claude Code agent → Daily retrospectives: writes retrospectives
- Daily retrospectives → Trading playbook: informs revisions
- Claude Code agent → Operator proposals: requests changes
- Human operator → Operator proposals: reviews requests
- Market watchers → Polymarket: checks listings
- Market watchers → Cycle launcher: triggers cycles
- Real execution → Execution caps: reads caps
- Real execution → Polymarket: places orders
- Real execution → Pearl Connect: requests signatures
- Human operator → Real execution: enables real mode
- Real execution → Paper ledger: records fills