Multi-LLM AI Trading Agent Harness

Notifications You must be signed in to change notification settings

Fork 2

Star 6

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

6 Commits

6 Commits

.github/assets

.github/assets

scripts

scripts

src

src

.env.example

.env.example

.gitignore

.gitignore

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

bun.lock

bun.lock

package.json

package.json

tsconfig.json

tsconfig.json

Repository files navigation

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 The Economist"]:::entry Screener["Screener Agent The Scout"]:::entry

Sentiment["Sentiment Mood Reader"]:::analysis Fundamental["Fundamental Accountant"]:::analysis Valuation["Valuation Appraiser"]:::analysis Catalyst["Catalyst Event Watcher"]:::analysis Risk["Risk Risk Manager"]:::analysis Technical["Technical Chart Reader"]:::analysis

Orchestrator["Orchestrator Agent The CIO"]:::synthesis Constructor["Portfolio Constructor The Trader"]:::execution Execute["Order Execution Alpaca API"]:::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

Loading

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

ALPACA_API_KEY / ALPACA_SECRET_KEY Bars, quotes, positions, news, order execution

FRED_API_KEY Macro indicators, interest rates

TAVILY_API_KEY Web search, page extract, site crawl

Yahoo Finance needs no key.

LLM providers — set at least one:

OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY, GLM_API_KEY, OPENROUTER_API_KEY

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 CLAUDE_CODE_EXECUTABLE 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.

ALPACA_API_KEY_ / ALPACA_SECRET_KEY_ — per-model paper credentials for execute. Falls back to the global ALPACA_* keys.

CLAUDE_CODE_EXECUTABLE — 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.

About

Multi-LLM AI trading agent harness.

investingbench.vercel.app

Topics

finance

typescript

ai

trading-bot

multi-agent

gemini

stock-market

openai

investment

algorithmic-trading

yahoo-finance

alpaca

autonomous-agents

ai-agents

bun

paper-trading

portfolio-management

llm

tool-calling

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

6 stars

Watchers

0 watching

Forks

2 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors 1

achaljhawar Achal Jhawar

Languages

TypeScript 100.0%