Pam Overview and MiroFish Assessment

Date: 2026-05-24
Repo: /Users/joshua/Projects/Unicorn.Land/pam

Executive Summary

Pam is in a technically healthy local state: the full test suite passes, the main CLI runs, the local status command can initialize and read the SQLite database, and the research status machinery reports a confident strategy gate. The main caveat is operational freshness: the research handoff says the latest state and latest scan are stale, even though candidate review itself hydrates successfully.

MiroFish is interesting as a research sandbox, but I would not integrate it directly into Pam’s live or execution paths. It is not really a small library; it is an AGPL-3.0 application stack with a Python/Flask backend, Vue frontend, OASIS/CAMEL agent simulation dependencies, Zep Cloud memory, and OpenAI-compatible LLM calls. The safest integration shape is a separately deployed, research-only service that emits structured scenario outputs into Pam’s research lab for backtesting and candidate review, never into execution without calibration and human review.

Recommendation: do not import MiroFish code into Pam. If we explore it, isolate it behind a process or service boundary, treat outputs as untrusted research features, and resolve AGPL obligations before anything commercial or hosted is exposed.

Current Pam State

Local Health Snapshot

• Branch: main, ahead of origin/main by 6 commits.
• Working tree note: repo-snapshot.zip is deleted in the local worktree and appears unrelated to this sweep.
• Test run: python3 -m pytest passes with 217 passed in 1.03s.
• Main status command: python3 main.py status runs successfully.
• Research status command: python3 main.py research-status runs successfully.

Runtime Status

From python3 main.py status:

• Database initialized at data/unicorn.db.
• Database counts are currently quiet for core signal flow: 0 articles, 0 signals, 0 trades, 0 stored arbitrage opportunities.
• Stored arbitrage trades: 12.
• Live trading engine reports enabled, test mode enabled, real API disabled.
• Live trading says it can trade under the current test-mode limits.
• Risk limits: 10 daily trades, 55 percent minimum confidence, $1 minimum trade size, 4-day max expiration.
• Arbitrage system is enabled with a 10-minute scan interval, 5 percent minimum spread, and 20 percent auto-execute threshold.

Important nuance: the local status output reports live trading enabled in test mode, while config.yaml.example shows live_trading.enabled: false. The active runtime config is therefore not just the example file; it comes from config.yaml, defaults, and environment overrides through runtime_config.py.

Research Status

From python3 main.py research-status:

• Status: ok.
• Cycle: 28.
• Last loop timestamp: 2026-04-02T21:42:05.314982+00:00.
• Confidence: true.
• Replay rows: 456.
• Score: 35.1.
• Hit rate: 0.675.
• Action count: 40.
• Unique tickers: 21.
• Stable cycles met: 3.
• Candidate review: gate ready, 0 deployable trades, 2 review candidates, 0 research candidates.
• Freshness warnings: latest state is stale and latest scan is stale.
• Top review blocker: scan_age_sec>900.

Interpretation: the research gate can classify the current replay as confident, but the live candidate surface should not be trusted until a fresh scan runs. The system is research-ready, not fresh-trade-ready.

Architecture

Pam has five major surfaces:

1. Signal ingestion and approval - RSS feed aggregation, content processing, translation, signal generation, Telegram approvals, and optional live-trading handling. - Main modules: core/, monitoring/, execution/, main.py.

2. Cross-venue arbitrage - Market discovery, Kalshi/Polymarket matching, spread analysis, Kelly sizing, liquidity checks, and execution policy. - Main modules: arbitrage/, matcher/, venues/, execution/.

3. Intra-venue arbitrage - Kalshi ladder and intra-venue relation detection, mirror/range grouping, detector tests, and daemon/alerting support. - Main modules: arbitrage/intra_venue/, arbitrage/kalshi_ladder_scanner.py, arbitrage/kalshi_ladder_daemon.py, intraarb.py.

4. Research lab - Replay preparation, experiment search, candidate review, status hydration, continuous loop orchestration, and Ralph/Codex handoff. - Main modules: research/, docs/ralph/, docs/prds/, scripts/run_ralph_pam_research.sh.

5. Dashboards and operations - Flask/FastAPI dashboards, background monitors, overlap watchers, catalog sync tools, deployment scripts, and ops policy. - Main modules: dashboard/, templates/, watchers/, tools/, ops/, policy/.

What Looks Solid

• Test coverage is broad for the highest-risk internal logic: candidate review, scanner gates, Kalshi ladder scanning, pairing, pricing, liquidity, Kelly sizing, matcher behavior, and research status.
• Runtime defaults in runtime_config.py are conservative for execution: test mode, real API disabled, auto approval disabled, capped test trades, capped risk, and explicit arbitrage thresholds.
• Research observability is unusually strong. research/latest_state.json, status hydration, replay profiles, sleeve concentration, ticker concentration, and blocker labels make it possible to distinguish a weak strategy from stale data or metadata gaps.
• The recent commits indicate active hardening around candidate review, scanner behavior, Kalshi ladder scanning, inventory-backed arbitrage, and matcher tolerance.

Gaps and Watch Items

• Freshness is the immediate operational gap. The latest research loop state and latest scan are stale, and current review candidates are blocked by scan age.
• There is config drift risk. config.yaml.example, runtime_config.py, and active config.yaml do not necessarily communicate the same operational posture. This matters for live-trading defaults and execution thresholds.
• DEPLOYMENT_STATUS.md appears historical. It references a specific monitor PID and market counts that should not be treated as current state without checking live processes/logs.
• Core signal database counts are currently zero, so the RSS-to-signal path may be dormant even though arbitrage/research surfaces are active.

MiroFish Research

What It Is

MiroFish describes itself as a multi-agent AI prediction engine that ingests seed material, builds a parallel digital world, simulates many agents, and returns a prediction report plus an interactive environment.

Source: MiroFish README

The repo is a full app, not a small package:

• Root scripts orchestrate backend and frontend setup/dev.
• Backend: Flask, Flask-CORS, OpenAI SDK, Zep Cloud, camel-oasis, camel-ai, PyMuPDF, Pydantic.
• Frontend: Vue, Vite, axios, D3, vue-i18n, vue-router.
• Deployment: Docker image and docker-compose expose frontend on 3000 and backend API on 5001.

Sources:

• package.json
• backend/pyproject.toml
• frontend/package.json
• docker-compose.yml

Integration Fit With Pam

Potentially useful:

• Scenario simulation for event-driven markets where crowd reaction matters.
• Narrative stress tests for politics, companies, macro, public-opinion, and policy markets.
• Generating hypotheses that Pam can then backtest through research/run_replay.py and candidate review.
• Producing structured rationale features for eventful market observation, if outputs are normalized and calibrated.

Poor fit:

• It is too large and stateful to place inside Pam’s hot arbitrage path.
• It is probabilistic, prompt-sensitive, and expensive. That conflicts with Pam’s low-latency arbitrage execution requirements.
• Its dependencies and license posture are not aligned with a closed-source or production trading stack unless isolated carefully.
• Its outputs are synthetic simulations, not market prices. They should influence research hypotheses, not order placement.

Security Assessment

Risk rating for direct integration: high.

Key findings:

• No authentication boundary is visible in the app factory. The backend registers /api/graph, /api/simulation, and /api/report, enables CORS for /api/* from any origin, and exposes a health endpoint.
• Config defaults include a hardcoded Flask secret fallback and debug enabled by default.
• The .env.example requires LLM and Zep API keys, meaning any deployment processes sensitive prompts, uploaded documents, and simulation memory through third-party services.
• File uploads are part of the backend config, with a 50 MB limit and support for PDF/Markdown/text. This creates an untrusted document-processing surface.
• The Docker Compose example runs a published latest image and exposes both app ports.
• The frontend development server uses vite --host and proxies /api to localhost backend, appropriate for dev but not a security boundary.
• GitHub issue #421 independently flags zero authentication on major APIs, prompt injection risk through interview endpoints, debug/default-secret problems, filesystem IPC races, and AGPL exposure as production blockers.

Sources:

• backend/app/init.py
• backend/app/config.py
• backend/run.py
• frontend/vite.config.js
• Issue #421

License Assessment

Risk rating for direct code integration: high.

MiroFish is AGPL-3.0 licensed. Its backend also depends on camel-oasis, and issue #421 calls out the AGPL network-use implications explicitly. For Pam, the practical rule is simple: do not import, copy, or modify MiroFish/OASIS code inside Pam unless we are prepared to satisfy AGPL obligations for the combined work and any network-exposed service.

Safer alternatives:

• Run an unmodified MiroFish instance as a separate internal research tool.
• Keep source publication obligations contained if we modify and expose the AGPL service.
• Use a clean API boundary and store only generated reports/features in Pam.
• Have counsel review before any commercial hosted use.

Source: MiroFish LICENSE

Proposed Integration Shape

Recommended architecture:

Pam research lab
  -> creates scenario packet from market/news/replay context
  -> sends packet to isolated MiroFish research service
  -> receives report plus structured probabilities/rationales
  -> stores result as research artifact, not trading signal
  -> evaluates through replay/candidate review before any use

Implementation guardrails:

• Do not import MiroFish packages into Pam.
• Do not run MiroFish in the same process as Pam.
• Do not give it exchange credentials, Telegram credentials, wallet keys, or Pam’s production .env.
• Use a dedicated API key, network allowlist, rate limits, per-run budgets, and strict request/response schemas.
• Strip or redact market/private data before sending to external LLM/Zep services.
• Treat reports as untrusted input: validate JSON, cap lengths, and never execute returned code or commands.
• Persist all MiroFish outputs under research/ with run metadata for auditability.
• Add calibration tests before letting a MiroFish-derived feature influence candidate state.

Suggested first experiment:

1. Pick 20 historical eventful markets already present in Pam’s replay rows.
2. Build minimal seed packets: market title, category, relevant news summary, current price, resolution date, and target question.
3. Run MiroFish manually outside Pam.
4. Convert outputs into a neutral research feature file, for example research/mirofish_experiments.jsonl.
5. Compare predictions against realized moves using Pam’s replay harness.
6. Only consider automation if the feature adds measurable lift over the current strategy baseline.

Bottom Line

Pam is locally test-clean and has a mature research/candidate-review layer, but it needs fresh scans before trade review is current. MiroFish is promising for offline scenario research, especially politics/public-opinion style markets, but the security, AGPL, cloud-data, and operational-complexity risks make direct integration the wrong move.

The pragmatic path is to treat MiroFish as an isolated research probe. If it proves predictive under replay, build a thin, audited adapter. If it does not produce measurable lift, keep Pam focused on its existing scanner, replay, and candidate-review loop.