feat: add authenticated Devin CLI bridge for LLM inference

README.md

@@ -156,6 +156,24 @@ For local models, configure Ollama with `llm_provider: "ollama"`. The default en
 
 For any other OpenAI-compatible server (vLLM, LM Studio, llama.cpp, or a custom relay), use `llm_provider: "openai_compatible"` and set the endpoint via `backend_url` (or `TRADINGAGENTS_LLM_BACKEND_URL`), e.g. `http://localhost:8000/v1` for vLLM or `http://localhost:1234/v1` for LM Studio. The model is whatever your server serves. No key is needed for local servers; set `OPENAI_COMPATIBLE_API_KEY` when the endpoint requires one.
 
+#### Devin CLI
+
+TradingAgents can also use an authenticated [Devin CLI](https://devin.ai) installation as its LLM backend via a local OpenAI-compatible bridge — no direct LLM-provider API key required for the LLM. Start the bridge in one terminal, then run TradingAgents in another:
+
+```bash
+# Terminal 1: start the bridge (uses the Devin CLI's configured/default model)
+python -m devin_bridge
+
+# Terminal 2: point TradingAgents at the bridge
+export TRADINGAGENTS_LLM_PROVIDER=openai_compatible
+export TRADINGAGENTS_LLM_BACKEND_URL=http://127.0.0.1:8765/v1
+export TRADINGAGENTS_QUICK_THINK_LLM=devin-quick
+export TRADINGAGENTS_DEEP_THINK_LLM=devin-deep
+tradingagents
+```
+
+To use a specific model, pass `--model <id>` (discover IDs with `python -m devin_bridge --list-models`). See [`devin_bridge/USER_GUIDE.md`](devin_bridge/USER_GUIDE.md) for full setup and troubleshooting. Data-provider credentials (FRED, Alpha Vantage, etc.) are separate and may still be required.
+
 Alternatively, copy `.env.example` to `.env` and fill in your keys:
 ```bash
 cp .env.example .env

devin_bridge/README.md

@@ -0,0 +1,123 @@
+# Devin Bridge
+
+An OpenAI-compatible local sidecar that routes TradingAgents LLM inference
+through an authenticated [Devin CLI](https://devin.ai) installation.
+TradingAgents keeps full control of graph orchestration, agents, prompts,
+schemas, and tool execution; the bridge only translates model responses.
+
+## Why
+
+TradingAgents already speaks the OpenAI-compatible protocol. The Devin CLI
+provides authenticated access to hosted models (e.g. GLM-5.2 High) without
+requiring a direct LLM-provider API key for the LLM. The bridge exposes the
+Devin CLI as a local `http://127.0.0.1:8765/v1` endpoint that
+TradingAgents can talk to with `provider=openai_compatible`.
+
+Data-provider credentials (FRED, Alpha Vantage, etc.) are separate from LLM
+credentials and may still be required depending on the analysts you select.
+
+## Prerequisite
+
+Install and authenticate the Devin CLI:
+
+```bash
+devin          # authenticate once
+devin -p ...   # verify it works
+```
+
+No Python package for `devin` is required — the bridge shells out to the
+`devin` executable on your `PATH`.
+
+## See available models
+
+```bash
+python -m devin_bridge --list-models
+```
+
+## Start the bridge
+
+Default — both quick and deep aliases use the model configured/defaulted by
+the authenticated Devin CLI (no `--model` flag passed to `devin -p`):
+
+```bash
+python -m devin_bridge
+```
+
+One explicit model for all aliases:
+
+```bash
+python -m devin_bridge --model <model-id>
+```
+
+Separate quick / deep models:
+
+```bash
+python -m devin_bridge \
+  --quick-model <quick-model-id> \
+  --deep-model <deep-model-id>
+```
+
+The bridge listens on `http://127.0.0.1:8765` by default. Verify with:
+
+```bash
+curl -s http://127.0.0.1:8765/healthz
+```
+
+## Configure TradingAgents
+
+```bash
+export TRADINGAGENTS_LLM_PROVIDER=openai_compatible
+export TRADINGAGENTS_LLM_BACKEND_URL=http://127.0.0.1:8765/v1
+export TRADINGAGENTS_QUICK_THINK_LLM=devin-quick
+export TRADINGAGENTS_DEEP_THINK_LLM=devin-deep
+export TRADINGAGENTS_LLM_MAX_RETRIES=0
+```
+
+## Run TradingAgents
+
+```bash
+tradingagents
+```
+
+TradingAgents chooses `devin-quick` for fast reasoning steps and
+`devin-deep` for deeper reasoning steps (Research Manager, Portfolio
+Manager). The bridge maps those aliases to actual Devin models.
+
+## Stop
+
+`Ctrl+C` in the bridge terminal. The bridge cleans up its runtime
+directory automatically.
+
+## Protocol
+
+The bridge uses a strict bounded-envelope protocol with two response kinds:
+
+- **FINAL** — raw bounded text for natural-language/Markdown assistant
+  content. Not JSON-encoded, so newlines, quotes, tables, and braces are
+  preserved verbatim.
+- **TOOL_CALLS** — strict JSON for tool requests and structured outputs
+  (ResearchPlan, TraderProposal, PortfolioDecision, SentimentReport).
+
+The parser is intentionally strict: malformed envelopes are rejected, not
+silently accepted. This is the trust boundary between Devin and
+TradingAgents.
+
+## Troubleshooting
+
+**Devin auth missing**: run `devin` once to authenticate, then restart the
+bridge.
+
+**Unavailable model**: run `python -m devin_bridge --list-models` and pick
+a model that is listed.
+
+**Port occupied**: stop any previous bridge process, or start with
+`--port <other-port>` and update `TRADINGAGENTS_LLM_BACKEND_URL` to match.
+
+**Malformed protocol response**: the bridge logs a sanitized protocol error
+(no raw content in normal mode). Restart with `--debug` to see a bounded
+raw tail for diagnosis. The bridge does not weaken its parser — malformed
+responses are rejected.
+
+**Missing optional data provider**: `FRED_API_KEY` is optional. If unset,
+macro data degrades gracefully and TradingAgents continues. Other data
+providers (yfinance, Reddit RSS, Polymarket) are keyless.

devin_bridge/USER_GUIDE.md

@@ -0,0 +1,110 @@
+# Devin Bridge — User Guide
+
+The Devin bridge lets TradingAgents use an authenticated Devin CLI
+installation as its LLM backend, instead of requiring a direct
+LLM-provider API key. TradingAgents' own tools, agents, prompts, and
+graph remain unchanged; only model inference is routed through Devin.
+
+## One-time setup
+
+```bash
+cd TradingAgents
+. .venv/bin/activate      # or: conda activate tradingagents
+```
+
+Make sure the `devin` CLI is installed and authenticated (`devin` works
+from your shell). No OpenAI, Anthropic, or other paid LLM-provider API
+keys are required for the LLM.
+
+## See available models
+
+```bash
+python -m devin_bridge --list-models
+```
+
+## Start the bridge (Terminal 1)
+
+Default — both quick and deep aliases use the model configured/defaulted by
+the authenticated Devin CLI (no `--model` flag passed to `devin -p`):
+
+```bash
+python -m devin_bridge
+```
+
+One explicit model for all aliases:
+
+```bash
+python -m devin_bridge --model <model-id>
+```
+
+Separate quick / deep models:
+
+```bash
+python -m devin_bridge \
+  --quick-model <quick-model-id> \
+  --deep-model <deep-model-id>
+```
+
+The bridge listens on `http://127.0.0.1:8765` by default and prints the
+mapped models on startup. Verify with:
+
+```bash
+curl -s http://127.0.0.1:8765/healthz
+```
+
+## Start TradingAgents (Terminal 2)
+
+```bash
+cd TradingAgents
+. .venv/bin/activate
+
+export TRADINGAGENTS_LLM_PROVIDER=openai_compatible
+export TRADINGAGENTS_LLM_BACKEND_URL=http://127.0.0.1:8765/v1
+export TRADINGAGENTS_QUICK_THINK_LLM=devin-quick
+export TRADINGAGENTS_DEEP_THINK_LLM=devin-deep
+export TRADINGAGENTS_LLM_MAX_RETRIES=0
+export TRADINGAGENTS_RESULTS_DIR=/tmp/tradingagents-results
+export TRADINGAGENTS_CACHE_DIR=/tmp/tradingagents-cache
+export TRADINGAGENTS_MEMORY_LOG_PATH=/tmp/tradingagents-memory/trading_memory.md
+export TRADINGAGENTS_CHECKPOINT_ENABLED=true
+
+tradingagents
+```
+
+Follow the interactive prompts to pick a ticker, date, and analysts.
+
+## How it works
+
+- TradingAgents chooses `devin-quick` for fast reasoning steps and
+  `devin-deep` for deeper reasoning steps (Research Manager, Portfolio
+  Manager).
+- The bridge maps those aliases to actual Devin models.
+- TradingAgents executes its own financial/data tools locally; the bridge
+  only translates model responses.
+- Data-provider credentials (e.g. `FRED_API_KEY`) are separate from LLM
+  credentials and are passed through to TradingAgents tools unchanged.
+
+## Stop
+
+Press `Ctrl+C` in the bridge terminal (Terminal 1). The bridge cleans up
+its runtime directory automatically.
+
+## Troubleshooting
+
+**Devin auth missing**: run `devin` once in your shell to authenticate,
+then restart the bridge.
+
+**Unavailable model**: run `python -m devin_bridge --list-models` and pick
+a model that is listed.
+
+**Port occupied**: stop any previous bridge process, or start with
+`--port <other-port>` and update `TRADINGAGENTS_LLM_BACKEND_URL` to match.
+
+**Malformed Devin protocol response**: the bridge logs a sanitized
+protocol error (no raw content in normal mode). Restart with `--debug` to
+see a bounded raw tail for diagnosis. The bridge does not weaken its
+parser — malformed responses are rejected, not silently accepted.
+
+**Missing optional data provider**: `FRED_API_KEY` is optional. If unset,
+macro data degrades gracefully and TradingAgents continues. Other data
+providers (yfinance, Reddit RSS, Polymarket) are keyless.

devin_bridge/__init__.py

@@ -0,0 +1,15 @@
+"""Devin Bridge — local OpenAI Chat Completions sidecar backed by the Devin CLI.
+
+This package implements a local HTTP server that translates OpenAI Chat
+Completions requests into fresh ``devin -p`` invocations using the
+authenticated Devin CLI. It is a separate sidecar — NOT part of the
+TradingAgents package. TradingAgents points its existing ``openai_compatible``
+provider at this server's loopback URL.
+
+Run with::
+
+    python -m devin_bridge
+    python -m devin_bridge --help
+"""
+
+__version__ = "0.1.0"