Trade-pilot

Trade-pilot is a full-stack trading assistant for Korean equities. It combines an analyst-style React web workspace, a FastAPI backend, OpenAI-powered agent workflows, deterministic risk controls, paper trading, and optional CREON Plus integration through a Windows gateway.

The project is designed as trading infrastructure scaffolding. It is not financial advice, and live brokerage access is disabled by default.

What It Does

Area	Functionality
AI assistant workspace	Users ask natural-language trading or portfolio questions and receive structured responses, not just chat text.
Multi-artifact answers	Responses can include text, metrics, tables, charts, decision cards, and grounded research summaries.
Skill-aware planning	The assistant inspects Markdown skill cards before choosing which internal capability to use. Missing capabilities are reported instead of invented.
Research grounding	A read-only provider boundary supplies market/news context; the default provider uses clearly labeled synthetic demo fixtures.
AI trade decisions	Specialist agents and a supervisor produce structured BUY, SELL, or HOLD decisions.
Backtesting	Historical decisions and a momentum strategy can be simulated against a buy-and-hold baseline with risk/turnover metrics.
Agent evaluation	An offline harness measures capability selection, structured output, invalid actions/symbols, hallucinated tools, and safety violations.
Portfolio analytics	Authenticated users can inspect symbol/sector allocation, unrealized PnL, data-quality notes, and concentration warnings.
Risk controls	Deterministic checks enforce confidence thresholds, position limits, order size limits, human approval, and live-trading gates.
Paper trading	The default broker is a safe paper adapter for local testing.
CREON Plus integration	Optional Windows-native gateway can bridge to CREON Plus / CYBOS Plus COM APIs.
Authenticated web app	Users can sign in and work with their own trading workspace data.
Admin console	Operators can inspect dashboard summaries, positions, recent decisions, transactions, and orders.

Applications

App	Path	Purpose
User web	user-web	Main analyst workspace for user-facing requests.
Admin web	admin-web	Admin dashboard for operations, review, and manual order flow.
Backend	backend	FastAPI API, auth, agent orchestration, risk, persistence, and broker adapters.
CREON gateway	gateway	Windows-native FastAPI gateway that owns CREON Plus COM calls.
Legacy mobile	frontend	React Native / Expo app retained while the user-facing experience moves to web.

System Architecture

flowchart LR
  User["User"] --> UserWeb["user-web<br/>React analyst workspace"]
  Admin["Admin"] --> AdminWeb["admin-web<br/>Operations dashboard"]
  Mobile["Legacy mobile app"] --> MobileApp["frontend<br/>React Native / Expo"]

  UserWeb --> API["FastAPI backend<br/>/api"]
  AdminWeb --> API
  MobileApp --> API

  API --> Access["Identity & access layer"]
  API --> Assistant["AssistantWorkspace<br/>request planner"]
  API --> Engine["TradingEngine<br/>decisions + orders"]
  API --> Analytics["PortfolioAnalytics<br/>exposure + PnL"]
  API --> Backtest["BacktestEngine<br/>simulation only"]
  API --> Eval["AgentEvaluationHarness<br/>offline checks"]
  API --> DB["PostgreSQL"]

  Assistant --> Skills["SKILLS catalog<br/>Markdown capability cards"]
  Assistant --> DB
  Assistant --> Engine
  Assistant --> Research["ResearchProvider<br/>local demo by default"]
  Assistant --> Artifacts["UI artifacts<br/>tables + charts + cards"]

  Engine --> Orchestrator["AgentOrchestrator<br/>specialists + supervisor"]
  Orchestrator --> Skills
  Orchestrator --> OpenAI["OpenAI API"]
  Engine --> Risk["RiskManager<br/>deterministic guardrails"]
  Engine --> BrokerFactory["Broker factory"]
  Engine --> DB

  BrokerFactory --> Paper["PaperBroker"]
  BrokerFactory --> CreonDirect["CreonBroker<br/>Windows COM"]
  BrokerFactory --> CreonGatewayBroker["CreonGatewayBroker<br/>HTTP client"]
  CreonGatewayBroker --> Gateway["Windows CREON Gateway"]
  Gateway --> Creon["CREON Plus / CYBOS Plus<br/>32-bit COM"]

Loading

Assistant Flow

flowchart TD
  Query["User query"] --> Planner["Assistant planner"]
  Planner --> Objective["Define complete objective"]
  Objective --> SkillCatalog["Inspect SKILLS catalog"]
  SkillCatalog --> ExistingSkills["Select available skills"]
  SkillCatalog --> MissingSkills["Report missing skills"]
  ExistingSkills --> Capabilities["Run needed capabilities"]

  Capabilities --> Status["system_status"]
  Capabilities --> Portfolio["portfolio_review"]
  Capabilities --> Orders["order_review"]
  Capabilities --> History["decision_history"]
  Capabilities --> Research["research provider context"]
  Capabilities --> Decision["trade_decision"]

  Status --> Response["AssistantQueryResponse"]
  Portfolio --> Response
  Orders --> Response
  History --> Response
  Research --> Response
  Decision --> Response
  MissingSkills --> Response

  Response --> UI["Rendered answer<br/>text + artifacts"]

Loading

Trading Decision Flow

sequenceDiagram
  participant UI as Web UI
  participant API as FastAPI
  participant Market as MarketDataService
  participant Research as ResearchProvider
  participant Engine as TradingEngine
  participant Agents as AgentOrchestrator
  participant Risk as RiskManager
  participant DB as PostgreSQL
  participant Broker as Broker adapter

  UI->>API: POST /api/assistant/query or /api/decisions/run
  API->>Market: Build market snapshot
  Market->>Broker: Get quote unless last_price was provided
  API->>Engine: Run decision
  Engine->>Research: Retrieve read-only context
  Engine->>Agents: Specialist agents + supervisor
  Agents-->>Engine: Structured trade decision
  Engine->>Risk: Apply deterministic guardrails
  Risk-->>Engine: APPROVED / REJECTED / NEEDS_APPROVAL
  Engine->>DB: Persist agent run and decision
  alt Auto execution enabled and risk approved
    Engine->>Broker: Submit order
    Broker-->>Engine: Broker result
    Engine->>DB: Persist order result
  else Hold or manual approval required
    Engine->>DB: Store decision without broker execution
  end
  Engine-->>API: Decision response
  API-->>UI: Answer and artifacts

Loading

Core Components

Component	Responsibility
AssistantWorkspace	Plans a user request as a full objective, selects needed capabilities, and returns a multi-artifact workspace response.
AgentOrchestrator	Uses OpenAI and the SKILLS catalog to run trading specialists and produce a structured decision.
TradingEngine	Persists agent runs and decisions, invokes risk checks, and coordinates order creation or approval.
RiskManager	Enforces non-negotiable safety boundaries outside the language model.
ResearchProvider	Separates read-only context retrieval from prompts and execution; defaults to synthetic local fixtures.
BacktestEngine	Simulates long/cash decisions and computes return, win rate, drawdown, Sharpe-like return, turnover, and rejections.
AgentEvaluationHarness	Runs deterministic planner, output-contract, hallucination, symbol/action, and risk-boundary tests.
PortfolioAnalyticsService	Computes authenticated allocation, exposure, unrealized PnL, and concentration warnings.
PaperBroker	Provides deterministic paper-mode quote/order behavior for development.
CreonGatewayBroker	Calls the Windows gateway for CREON quotes, accounts, orders, status refresh, and cancellation.
gateway	Runs on Windows and owns serialized CREON Plus COM interaction.
PostgreSQL	Stores application data for users, decisions, agent payloads, orders, and positions.

Runtime Services

Service	Default URL / Port	Notes
User web	http://localhost:5174	Main user-facing web app.
Admin web	http://localhost:5173	Admin operations dashboard.
Backend API	http://localhost:8000	FastAPI routes and OpenAPI docs.
PostgreSQL	localhost:5432 or configured POSTGRES_PORT	Docker-backed local database.
CREON gateway	http://WINDOWS_HOST:8765	Optional Windows service for CREON Plus.

Quick Start

Create local configuration from the safe paper-mode template:

cp .env.example .env

Start the default paper-trading stack:

docker compose up --build -d

Open:

Surface	URL
User workspace	http://localhost:5174
Admin dashboard	http://localhost:5173
Backend API	http://localhost:8000

Open http://localhost:8000/docs for the authenticated API contract. Register a user through the user web app or /api/auth/register.

Optional demo data

The idempotent seeder creates synthetic positions, one HOLD decision, and one paper fill. It never calls a broker. If the demo user does not exist, provide a new password through an environment variable:

docker compose exec -e DEMO_USER_PASSWORD='replace-with-12-plus-chars' \
  backend python -m app.demo_seed

Local backend development

cd backend
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
alembic upgrade head
uvicorn app.main:app --reload

Research, Evaluation, and Analytics APIs

Endpoint	Auth	Behavior
POST /api/research/query	User	Retrieves provider context. local_demo is synthetic and never current news.
POST /api/backtests/run	User	Runs long/cash simulation and a buy-and-hold baseline; never contacts a broker.
GET /api/portfolio/analytics	User	Returns symbol/sector exposure, allocation, unrealized PnL, and warnings.
GET /api/evaluations/agent	Admin	Runs the deterministic offline agent harness.

Run backend tests, lint, and the agent evaluation report:

cd backend
python -m pytest tests -q
python -m ruff check app tests
python -m app.evaluation.cli --format json
python -m app.evaluation.cli --format markdown --output agent-evaluation.md

Build both maintained web apps:

npm --prefix user-web ci && npm --prefix user-web run build
npm --prefix admin-web ci && npm --prefix admin-web run build

Safety Boundaries

• BROKER_MODE=paper, AUTO_EXECUTE=false, ALLOW_LIVE_TRADING=false, and I_UNDERSTAND_LOSS_RISK=false are the tracked defaults.
• The LLM can only propose a structured decision. RiskManager remains a deterministic gate and broker submission remains inside TradingEngine.
• The local research provider is synthetic demo data. It is never labeled as current news and cannot place orders.
• Backtests and evaluations are simulation/testing features. They never call a broker and do not demonstrate or promise profitability.
• Realized PnL is reported as unavailable until authoritative average fill prices are persisted. The service does not substitute limit prices.

Detailed runbooks: architecture, research providers, backtesting and agent evaluation, and portfolio analytics, and production/safety.

CREON Plus Integration

CREON Plus is Windows-only and COM-based. The recommended live topology is to run the main app stack normally and run the CREON gateway on a separate Windows host or VM where CREON Plus is installed and logged in.

Requirement	Why it matters
Windows host or VM	CREON Plus depends on Windows COM and an interactive desktop login state.
32-bit Python process	CREON Plus COM APIs require a 32-bit caller.
CREON Plus installed and logged in	Quote and order COM objects depend on the active HTS session.

docker compose up --build -d does not create a Windows VM, install CREON Plus, or complete brokerage login. Those steps must be handled on the Windows machine.

Repository Layout

Trade-pilot/
  backend/                  FastAPI backend, agents, risk, DB models, broker adapters
    app/research/           Pluggable context providers and synthetic demo fixtures
    app/backtesting/        Deterministic strategy simulator and metrics
    app/evaluation/         Offline agent evaluation harness and CLI
    app/analytics/          Portfolio exposure, PnL, and warning service
  user-web/                 React/Vite user workspace
  admin-web/                React/Vite admin dashboard
  frontend/                 Legacy React Native / Expo app
  gateway/                  Windows CREON Plus gateway
  backend/app/skills/       Markdown skills injected into assistant prompts
  infra/windows/            Windows gateway setup helper
  scripts/                  Local development helper scripts
  .github/workflows/ci.yml  Backend, web-build, and Compose validation
  docker-compose.yml        Default paper-mode local stack
  docker-compose.creon-gateway.yml
  docker-compose.windows.yml

Status

Trade-pilot is an evaluation-oriented engineering scaffold, not a production trading system or financial-advice product. The implemented research provider is demo-only, historical prices must be supplied to backtests, and realized PnL requires a future authoritative execution ledger. Treat live brokerage connectivity as a separate production-hardening project and validate the full lifecycle in paper mode before considering live execution.