1rok

1rok is a standalone harness for running portfolio-construction agents across OpenAI, Anthropic, Gemini, xAI, DeepSeek, GLM, and OpenRouter against the same financial tool surface. Agents query Alpaca, Yahoo Finance, FRED, and Tavily through an inline, in-process tool registry defined in this repo.

Live leaderboard tracking how each model's portfolio performs in paper trading on Alpaca (started 2026-01-20): investingbench.vercel.app.

[!NOTE]

run produces an artifact. execute places orders. They are always separate commands. run never touches a broker; execute --live is the only path to real order placement.

Features

• Inline tool registry — listTools / callTool over local handlers; one registry per pipeline run.
• Eight tool groups — market, stock, research, technicals, options, earnings, portfolio, Tavily web search.
• Seven LLM providers — OpenAI (GPT-5.2/5.4/5.5), Anthropic (Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5), Gemini, xAI, DeepSeek, GLM, OpenRouter — behind a single tool-calling loop.
• Specialist agents — orchestrator, screener, fundamental, valuation, technical, sentiment, catalyst, macro, risk, constructor.
• Two-stage pipeline — run emits a portfolio-construction JSON artifact; execute reads it and places orders via Alpaca (paper by default).
• Provider-agnostic schemas — Zod definitions converted to each provider's tool-call format with shared retry/loop logic.

Agent Pipeline

Four stages, ten agents, one weekly run. Macro reads regime; Screener surfaces 25–30 candidates; six analysts score in parallel; Orchestrator composites; Constructor sizes trades; Alpaca executes (paper by default).

flowchart TD
    Macro["Macro Agent<br/><i>The Economist</i>"]:::entry
    Screener["Screener Agent<br/><i>The Scout</i>"]:::entry
Sentiment["Sentiment<br/><i>Mood Reader</i>"]:::analysis     Fundamental["Fundamental<br/><i>Accountant</i>"]:::analysis     Valuation["Valuation<br/><i>Appraiser</i>"]:::analysis     Catalyst["Catalyst<br/><i>Event Watcher</i>"]:::analysis     Risk["Risk<br/><i>Risk Manager</i>"]:::analysis     Technical["Technical<br/><i>Chart Reader</i>"]:::analysis
Orchestrator["Orchestrator Agent<br/><i>The CIO</i>"]:::synthesis     Constructor["Portfolio Constructor<br/><i>The Trader</i>"]:::execution     Execute["Order Execution<br/><i>Alpaca API</i>"]:::execution
Macro --> Screener     Screener --> Sentiment     Screener --> Fundamental     Screener --> Valuation     Screener --> Catalyst     Screener --> Risk     Screener --> Technical
Sentiment --> Orchestrator     Fundamental --> Orchestrator     Valuation --> Orchestrator     Catalyst --> Orchestrator     Risk --> Orchestrator     Technical --> Orchestrator
Orchestrator --> Constructor     Constructor --> Execute
classDef entry stroke:#ff8c00,stroke-width:2px     classDef analysis stroke:#888,stroke-width:1px     classDef synthesis stroke:#22c55e,stroke-width:2px     classDef execution stroke:#aaa,stroke-width:1px

Composite scoring weights: fundamental 20%, valuation 20%, risk 15% (inverted), technical 15%, catalyst 15%, sentiment 10%, macro gate 5%. Constructor caps at 8 positions, ≥85% invested, ≤40% per name.

Architecture

CLI (run | execute)
   │
   ▼
Provider ── TradingPipeline ── InlineToolRegistry (per run)
                │                       │
                ▼                       ▼
        Specialist agents ───── Tool handlers
                                        │
                                        ▼
                              src/data/services
                                        │
                                        ▼
                Alpaca · Yahoo Finance · FRED · Tavily

• Runner builds provider + TradingPipeline from model id.
• Pipeline instantiates one InlineToolRegistry per run.
• Agents execute through provider's tool-calling loop.
• Tool handlers call typed services in src/data.
• Services hit external APIs.

Layout

| Path | Role | |---|---| | src/data | Provider clients, domain services, types | | src/tools | Inline tool definitions + registry (listTools / callTool) | | src/harness/agents | Specialist agents (orchestrator, constructor, …) | | src/harness/providers | Provider adapters + tool-loop | | src/harness/pipeline | Run orchestration | | src/cli/1rok.ts | CLI entrypoint (run, execute, help) |

Requirements

• Bun >= 1.1.0 — supported on macOS (x64/arm64), Linux (x64/arm64, glibc or musl), and Windows (x64/arm64).
• API keys for the providers you intend to exercise (see Environment)

Quick Start

macOS / Linux (bash/zsh):

bun install
cp .env.example .env   # fill in keys you actually need
bun run typecheck

Windows (PowerShell):

bun install
Copy-Item .env.example .env   # fill in keys you actually need
bun run typecheck

Windows (cmd.exe):

bun install
copy .env.example .env
bun run typecheck

Run a portfolio-construction pipeline:

bun run 1rok -- run --model gpt-5.2-medium

Execute the resulting orders file (paper by default). Path separators differ per OS:

# macOS / Linux
bun run 1rok -- execute ./results/openai/gpt-5.2-medium/portfolio-construction-2026-04-16T07-00-00.json

# Windows PowerShell
bun run 1rok -- execute .\results\openai\gpt-5.2-medium\portfolio-construction-2026-04-16T07-00-00.json

[!WARNING]

--live places real orders. Without it, execution targets paper-api.alpaca.markets.

bun run 1rok -- execute ./results/<...>.json --live
bun run 1rok -- execute ./results/<...>.json --live --force

Install the CLI globally on your shell:

bun link
1rok run --model gpt-5.2-medium
1rok execute ./results/<...>.json

On Windows, bun link creates a 1rok.cmd shim on PATH; the commands above work unchanged from PowerShell or cmd.

Environment

Copy .env.example to .env. Nothing is required unless you exercise that integration.

Data providers

| Var | Purpose | |---|---| | ALPACAAPIKEY / ALPACASECRETKEY | Bars, quotes, positions, news, order execution | | FREDAPIKEY | Macro indicators, interest rates | | TAVILYAPIKEY | Web search, page extract, site crawl |

Yahoo Finance needs no key.

LLM providers — set at least one:

OPENAIAPIKEY, ANTHROPICAPIKEY, GEMINIAPIKEY, XAIAPIKEY, DEEPSEEKAPIKEY, GLMAPIKEY, OPENROUTERAPIKEY

Anthropic models

| Model id | Notes | |---|---| | claude-opus-4-7 | Default Anthropic model | | claude-opus-4-7-high | Reasoning effort high | | claude-opus-4-7-max | Reasoning effort max | | claude-sonnet-4-6 | | | claude-haiku-4-5 | |

The Anthropic adapter runs through @anthropic-ai/claude-agent-sdk, which ships a native claude binary as an optional dependency. The provider resolves that binary automatically for macOS (darwin-arm64, darwin-x64), Linux (linux-x64/arm64, glibc + musl), and Windows (win32-x64, win32-arm64). Override the resolved path with CLAUDECODEEXECUTABLE if needed (e.g. pointing at an existing claude install, or claude.exe on Windows).

Optional

• IROK_MODEL — default model id when --model is omitted.
• ALPACAAPIKEY<PROVIDER> / ALPACASECRETKEY<PROVIDER> — per-model paper credentials for execute. Falls back to the global ALPACA_* keys.
• CLAUDECODEEXECUTABLE — absolute path to the claude binary the Anthropic provider should use. Only needed if auto-resolution from the SDK's optional deps fails.

Scripts

bun run typecheck   # tsc --noEmit
bun run build       # tsc
bun run test        # bun test
bun run 1rok -- ... # CLI passthrough

Tool Groups

market, stock, research, technicals, options, earnings, portfolio, tavily. Each group registers Zod-typed definitions in src/tools/definitions/* and is aggregated through ALL_TOOLS in src/tools/definitions/index.ts.

Programmatic Use

import { createProviderFromModel } from "1rok/harness";
import { TradingPipeline } from "1rok/pipeline";
const provider = createProviderFromModel("gpt-5.2-medium"); const pipeline = new TradingPipeline({ provider }); const result = await pipeline.run();

Subpath exports: 1rok/tools, 1rok/data, 1rok/harness, 1rok/providers, 1rok/agents, 1rok/pipeline.