# Local AI Stock Bot v1.1.0

Local AI Stock Bot is a free, MIT-licensed local research and trading toolkit. It has one codebase with two modes: credential-free paper trading by default, and an advanced official-MCP handoff behind explicit configuration gates.

[Product page and download](https://agentmediatools.com/stock-bot) · [GitHub source](https://github.com/Pedregoneric/agentic-trading-lab) · [Stock Intelligence](https://agentmediatools.com/stock-intelligence) · [Optional tip](https://agentmediatools.com/tip?from=stock-bot)

## Optional Pro filing feed for Mira

The download is free forever. If you have **Agent Media Tools Pro**, set a Pro agent key so Mira’s research cycle can include hosted public filings (Form 4, House PTR, Form 144, 13D/G, curated 13F, and Mira’s plain-English daily brief).

```bash
# private .env
AMT_AGENT_KEY=mt_your_pro_key
```

No key → free bot unchanged (fail-soft). Not financial advice; always verify original filings. Details: [product page § Pro filing intel](/stock-bot#pro-intel) · [API docs](/docs/stock-intelligence).

## Install and verify

```bash
tar -xzf local-ai-stock-bot-v1.1.0.tar.gz
cd local-ai-stock-bot-v1.1.0
./setup.sh
source venv/bin/activate
python -m unittest discover -s tests -v
```

The setup creates a private `.env` from the included example. On first dashboard launch, a token-protected browser wizard configures the dashboard password and local or hosted OpenAI-compatible LLM. Hosted keys are saved only in `.env` with mode `0600`; non-secret provider/model settings go in `config/monitor_config.json`. The bot never accepts Robinhood credentials.

## Paper mode

The distributed configuration contains:

```json
{
  "trading_mode": "paper",
  "live_trading": false,
  "live_trading_acknowledgement": ""
}
```

Start a virtual portfolio:

```bash
python run_paper.py --reset --initial-cash 1000
python run_paper.py --summary
./launch_monitor.sh
```

Paper execution validates positive prices, amounts, cash, shares, and symbols. Portfolio files use atomic replacement. Simulations still omit some real-world spread, slippage, fees, partial fills, settlement, and tax effects.

## Mira, Nova, and Vesper

The default growth workflow is a visible three-agent decision room:

- Mira gathers current research.
- Nova compares candidates and proposes actions.
- Vesper reviews risk and explicitly chooses `PROCEED`, `REVISE`, or `HOLD_FOR_NOW`.

An entry requires all three stages. Critic failures, missing agents, malformed output, and debate timeouts fail closed. Live approvals expire after ten minutes and authorize only one submission for each approved symbol. Paper-only fast paths are disabled by default and can never submit live orders.

Vesper reviews complete structured proposals rather than ticker-level ideas. Each proposal must include its side, dollar size, order type, evidence timestamp, expiry, maximum loss, thesis risks, and an observable invalidation condition. Deterministic code rejects stale evidence, unsupported or unresearched symbols, duplicate positions, halted stocks, excessive spreads, insufficient buying power, oversized positions, and excess loss budgets. Approval is bound to the exact reviewed fields, so changing the size or order details invalidates it.

Use `compare_paper_runs.py` to compare isolated one-agent and three-agent portfolios under matched data and risk assumptions. It reports return, drawdown, expectancy, turnover, and sample size. This is an evaluation aid, not evidence that either system will make money.

All personas use the primary configured model unless optional `llm.roles.mira`, `llm.roles.nova`, or `llm.roles.vesper` model overrides are supplied.

## Live mode

Live mode requires all three settings exactly:

```json
{
  "trading_mode": "live",
  "live_trading": true,
  "execution_provider": "robinhood_agentic_mcp",
  "live_trading_acknowledgement": "I UNDERSTAND THIS CAN PLACE REAL-MONEY ORDERS"
}
```

Startup fails for incomplete/contradictory settings or a live configuration that bypasses market hours. Live analysis also requires an Agentic-account snapshot published within the last five minutes.

Robinhood now supports external agents through a dedicated Agentic Trading account and its official Trading MCP at `https://agent.robinhood.com/mcp/trading`. Connect that endpoint in a supported agent host and complete Robinhood's desktop authentication/onboarding. Direct orders through the bot's legacy `robin_stocks` data adapter are disabled; never give the bot your Robinhood password, MFA seed, session cookie, or MCP token.

Connect the same host to the package's local `agentic_bridge_server.py`. The monitor queues one exact approved proposal; the host claims it, submits those unchanged fields through Robinhood's MCP, records Robinhood's acknowledgement, and refreshes the Agentic-account snapshot. Expired proposals, stale snapshots, non-Agentic account types, duplicate claims, and accepted responses without a broker order ID fail closed. See `AGENTIC_TRADING.md` in the package.

## Dashboard

Run:

```bash
./launch_dashboard.sh
```

If configuration is incomplete, open the one-time setup URL printed in the terminal. Choose LM Studio/Ollama, DeepSeek, Grok, or another OpenAI-compatible endpoint; enter its model and optional per-agent model overrides; then create a long dashboard password. Sign in at `http://127.0.0.1:5001` with username `hermes`. The setup link disables itself afterward. The page and every data API require authentication, and the wizard always preserves paper mode. Suggestions are bounded untrusted research notes and cannot execute orders.

The dashboard does not automatically start the agents because analysis cycles can consume paid API usage. It clearly reports “Dashboard only” until the user explicitly runs `./launch_monitor.sh`; Agent Chat begins filling after the monitor reaches an LLM analysis cycle.

## Capabilities and limits

- The static universe currently contains 611 unique symbols; normal runs screen rotating bounded subsets rather than every symbol each cycle.
- Four conventional strategy modules form the fallback ensemble. When growth mode is enabled, the LLM growth/scalp path drives the main opportunity flow.
- Backtesting requires an explicit strategy callback and is educational, not performance proof.
- No returns, fill rate, profitability, or safety outcome is guaranteed.
- Optional Finnhub, FRED, LLM, and notification credentials must be supplied by each user. Robinhood authentication remains in the user's MCP host.
- This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.
- Yahoo, Finnhub, Robinhood, Reddit, and other integrations remain subject to their owners' terms.

## Configuration

See `.env.example`, `config/monitor_config.json`, and the package `README.md`. Do not commit `.env`, logs, broker sessions, or portfolio data.

## License and disclaimer

MIT license. This is experimental software, not investment, legal, tax, or financial advice. Trading can result in substantial loss.