Alpha-Dojo/DojoAgents

DojoAgents is a full-market AI agent framework designed specifically for personal investment. Built to bridge the gap between individual investors and institutional-grade tools, its true powerhouse is a state-of-the-art Agent Loop engine. Instead of a simple dashboard, DojoAgents deploys an autonomous reasoning agent that lives alongside your portfolio, handling everything from full-market data cognition to dynamic cross-market strategy deduction.

Seven-layer architecture — from CLI, Web Dashboard, and Chat Gateways through Agent Loop to tools, data, and infrastructure.

🧠 Loop-Driven Cognitive Portfolio Agent (Our Core Engine): Most financial AI tools are built for quick outputs: news summaries, single-stock explanations, basic indicator readings, or generic market commentary. Our Loop-Driven Cognitive Portfolio Agent is built for portfolio-aware reasoning, connecting your holdings with market data and running structured analysis across four dimensions:

• Fundamental Data Cognition: Instantly fetches, structures, and cross-references raw multi-market data (K-lines, financials, news).
• Advanced Logic Analysis: Interprets valuation bands, momentum indicators, and sector taxonomy to uncover hidden market mechanics.
• Cross-Market Strategy Deduction: Formulates macro asset allocation and maps market linkages (e.g., autonomously reasoning through "Why US semiconductor software dropped while A-shares surged" via multi-step tool execution).
• Dynamic Portfolio Management: Continuously diagnoses risk exposure, monitors net-worth curves, and evaluates performance attribution to support more informed rebalancing decisions.

📊 Four-Pillar Dashboard: An out-of-the-box, institutional-grade React SPA featuring:

• Portfolio (The Command Center): Net worth curves, live risk exposure, and smart position tracking.
• Markets: Cross-market heatmaps (US/HK/A-shares) and index tracking.
• Sectors: Deep-dive L1/L2/L3 taxonomy and momentum curves.
• Equities: K-lines, PE bands, financials, and news—all in one unified view.

🤖 Autonomous Quant Analyst: Powered by multi-agent collaboration, it autonomously conducts background market research, tracks sector rotations, and monitors your risk exposure while you sleep.

📱 Planned Omnichannel Updates: Future versions will support personalized daily briefings and alert notifications through Slack, Telegram, Discord, Feishu, WeChat, or email.

"What's worth watching in global markets today?" — one of the most common questions investors ask every morning. Behind it lies cross-market moves, sector rotation, stock anomalies, sentiment, and potential catalysts.

DojoAgents enters a data-gathering phase, calling global market, sector, and equity tools to pull movers, strength rankings, price changes, volume shifts, and sector distribution across A-shares, US equities, and HK stocks. Throughout the run, expand any intermediate step to see which tools were invoked, what data was cited, and how the analysis progressed.

When breaking news hits, the first question is always: which stocks will be affected?

Take Meta's recent AI infrastructure moves — A-share investors naturally asked: "Meta selling compute capacity — which US and A-share stocks could be impacted?" DojoAgents decomposes the question, then gathers data via market, news, company, and sector tools: Meta's price action, related headlines, market performance, and segments like US tech, AI compute chains, semiconductors, cloud, and ad-tech.

DojoAgents supports multimodal models — upload a holdings screenshot and get a full portfolio diagnosis. No manual data entry required.

Upload a screenshot with 40+ positions spanning A-shares, US stocks, and ETFs. DojoAgents recognizes each holding, re-groups them by market, sector, and supply-chain position, then generates a risk diagnosis — flagging over-concentration, overlapping exposure, and insufficient defensive assets. Despite 40+ names, many positions effectively bet on the same theme; a broad pullback in semiconductors, AI compute, or growth stocks could drag the entire portfolio down together.

After the diagnosis, DojoAgents proposes follow-up strategies — trim duplicate positions, keep core names, optimize US allocation, reduce weak exposures, and add defensive assets like utilities and consumer staples. Once you approve the recommendations, it can generate a new watchlist portfolio and track it continuously in the Dashboard.

Deploying your DojoAgents environment is designed to be frictionless. We strongly recommend using uv for lightning-fast dependency management.

• Python >= 3.11
• Node.js: >= 18 (for frontend build)
• npm: >= 9
• An LLM API Key (OpenAI, Gemini, Anthropic, etc.)

For most users, install the published package directly—no clone or frontend build required:

# macOS / Linux
uv venv && source .venv/bin/activate
uv pip install dojoagents

# Windows (PowerShell)
uv venv && .venv\Scripts\Activate.ps1
uv pip install dojoagents

# Windows (CMD)
uv venv && .venv\Scripts\activate.bat 
uv pip install dojoagents

Then skip to Launching the Server.

Runtime dependencies are listed in both pyproject.toml and requirements.txt.

# 1. Create and activate a virtual environment
uv venv && source .venv/bin/activate

# 2. Install in "editable mode" with dev tools. Any source code changes will take
# effect immediately—perfect for building custom tools or debugging the Agent Loop.
uv pip install -e ".[dev]"

The DojoAgents Dashboard is a high-performance React SPA powered by Vite, communicating with a FastAPI backend via an OpenAI-compatible chat API and SSE streaming for dynamic Canvas chart rendering.

If you are building from source, you will need Node.js (>= 18) and npm (>= 9).

cd dojoagents/dashboard/web
npm install
npm run build

dojoagents dashboard --host 127.0.0.1 --port 8765

Open http://127.0.0.1:8765/ in your browser to access your personal financial command center.

Once the dashboard is live, click on the Settings icon. DojoAgents features a comprehensive graphical interface to securely configure your preferred Large Language Models.

• Supported Providers: Out-of-the-box presets for OpenAI, Anthropic, Google Gemini, Zhipu GLM, and DeepSeek.
• Local & Custom Endpoints: Easily override Base URLs to connect to local instances like Ollama, llama.cpp, or vLLM.
• Secure Storage: All API keys and endpoint settings entered in the UI are securely written to your local ~/.dojo/agents.yaml file.

As illustrated in the diagram above, DojoAgents is engineered for scale, deep contextual reasoning, and absolute privacy.

• Agent Loop Engine: The core reasoning runtime. Handles multi-turn tool orchestration, context window compression, and strict guardrails to prevent financial hallucinations.
• Execution Sandbox: A secure, isolated environment for on-the-fly Python code execution, technical indicator calculations, and local web data extraction.
• Memory & SKILLS: Automatically distills successful, multi-step market analysis workflows into reusable, programmatic SKILLS for future execution.
• Cron & Gateway: Decoupled delivery pipelines that push scheduled, automated insights directly to your preferred chat applications, without blocking the main Agent reasoning loop.

An agent instance is bound to exactly one Harness instance. Core owns the LLM loop, tool execution, lifecycle and principal-scoped Session platform; the Harness owns one scenario's identity, prompts, skills, tools, memory, policies, tasks, presenters, services and surface adapters. The built-in financial scenario is selected by default:

harness:
  id: financial
  factory: dojoagents.harnesses.built_in.financial:create_harness
  config:
    backend: sdk

Other projects can provide a Python Harness factory or set factory: null and manifest: ./my-harness.yaml for the constrained dojoagents/v1alpha1 declarative format. Extra skill/tool directories supplement the bound Harness and cannot silently replace its owned components.

The Financial Harness owns agent behavior—prompts, ToolSpecs, policies, memory, tasks, and result presentation. The FastAPI Dashboard independently owns the financial application backend—routers, API schemas, stores, refresh/precompute jobs, portfolio data, and service lifecycle. Embedded Dashboard deployments bind their existing financial backend into Runtime; CLI or Gateway deployments can use the standalone SDK backend or a configured remote HTTP backend.

Sessions are scoped by (tenant_id, user_id, session_id) and can use file or project-provided stores. See the external SessionStore / BlobStore adapter contract for online MySQL/PostgreSQL/object-storage deployments.

Ready to build custom quantitative skills, integrate proprietary data, or deploy a multi-agent swarm? Dive into our comprehensive developer guides:

• System Architecture & Design Philosophy
• Writing Custom Plugins & Claude Skills
• Chat Gateways & Omnichannel Setup
• Dashboard UI Customization Guide
• External SessionStore / BlobStore adapters

We are building the ultimate open-source financial AI, and we'd love your help! Check out our Contribution Guidelines to see how you can add new tools, refine the agent prompts, or expand market coverage.

License: DojoAgents is open-source under the Apache License 2.0.

This project is for educational, research, and demonstration purposes only and does not provide investment advice or trading recommendations. Trading financial instruments involves significant risk, including possible loss of capital. All data, analysis, and outputs are for reference only and may not be accurate, complete, or up to date. Users are responsible for their own investment decisions, and this project and its contributors are not liable for any loss resulting from reliance on the information provided. Third-party names, logos, and brands are used for identification purposes only and do not imply endorsement or affiliation.