# Foresixa Quant 0.1.0

Private local MCP plugin and executable paper simulation prototype. Requires Python 3.11+ only. It has no broker-order methods, live switch, paid AI dependency or autonomous entry strategy. Twelve tools are available over stdio. Credentials are needed only for the read-only paper account check; quote-feed availability depends on provider access. A continuous 90-day trading trial has **not started**.

## Local use

Install the package into a host supporting local Agent Plugins and MCP stdio. `mcp.json` invokes `python3 runtime/server.py` with the host-resolved `${PLUGIN_ROOT}`. An account-saved plugin does not deploy its server or give ChatGPT web direct access to your laptop.

Invoke `quant_status`, then `initialize_simulation` with `virtual_cash: "25000"`. This creates an explicit local virtual account, not a broker account. The runtime stores its SQLite ledger at `~/.local/share/foresixa-quant/ledger.sqlite3`; override with `QUANT_DB_PATH` outside the plugin directory. Never use a real portfolio database. There is no implicit reset.

Research may be supplied to `evaluate_risk` or `simulate_entry` using the structure in `cognitive_bot.md`. Use a unique request ID per entry. Use complete timestamped quote sets with `mark_positions`; it monitors local stops and drawdown exits. `tax_workpaper` returns annual simulated disposition JSON. `performance_report` returns economic results after the configured modeled 25-basis-point entry and exit fee. Price slippage is reserved in sizing but is not dynamically sampled. One full lot per symbol; partial fills, partial disposals, bid/ask depth and multi-account tax matching are not implemented.

For a read-only feed loop with local stop monitoring:

```bash
python3 runtime/worker.py --once
python3 runtime/worker.py
```

The loop collects quotes every 15 seconds, emits separate heartbeat records, and never creates entry signals. It requires a continuously available host. A FEED_OK heartbeat establishes successful local processing, not complete strategy/broker health. Feed errors preserve positions and halt quote-dependent processing; they cannot guarantee an exit during an outage.

The exact paper endpoint is `https://paper-api.alpaca.markets`; `https://alpaca.markets` is a website. Store actual paper-only keys as `ALPACA_PAPER_KEY` and `ALPACA_PAPER_SECRET` through a local secret mechanism, never in chat or this source. Copy `.env.example` to a private file and set mode 600 if needed; Python does not automatically load dotenv files. No posted credentials are included in the package. Rotate any genuine credentials previously pasted.

## Database deployment

The tested runtime uses SQLite with atomic write reservations and decimal values stored as strings. `sql/init_system.sql` is the consolidated PostgreSQL deployment design, with schemas, references, constraints and restricted reader/runtime roles. It is a separate deployment artifact; this runtime does **not** write PostgreSQL. Execute it using a migration administrator only after reviewing on a new isolated PostgreSQL instance. Docker/PostgreSQL execution and role checks were unavailable during creation. Do not run it against an existing ledger expecting an automatic migration; back up and reconcile existing data first.

`compose.yaml` can run the collector. Its optional `schema-preview` PostgreSQL profile allows later schema verification; it is not the runtime's storage backend. No futures container is started, and no fictitious Alpaca futures keys are requested.

## Review and continuity

`trial_review` always reports review-required and zero verified trial days for this release. Before a true trial, supply an approved deterministic entry strategy, its data/evidence providers, risk exit/recovery design, a broker sandbox adapter with idempotent submissions and fill reconciliation, tested backups and durable monitoring. Futures additionally need a suitable broker and specifications. Infrastructure/data charges and computer uptime are external to this package; no $0 total-cost promise is made.

Run `python3 -m unittest discover -s tests -v`. Source examples and tests are synthetic. Test results are not market accuracy or independent governance approval. Snapshot the stopped local SQLite ledger with SQLite's backup API; preserve the source archive/hash and test restoration in a separate directory before relying on it for continuity.

Official references, checked October 4, 2026:

- https://docs.alpaca.markets/us/docs/paper-trading
- https://docs.alpaca.markets/us/docs/crypto-trading
- https://www.irs.gov/individuals/international-taxpayers/frequently-asked-questions-on-digital-asset-transactions
- https://www.irs.gov/instructions/i8949
- https://www.irs.gov/pub/irs-pdf/f6781.pdf (includes instructions)
- https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
- https://modelcontextprotocol.io/specification/2025-03-26/server/tools