rmi-backend/AGENTS.md

🚨 CRITICAL RULES (enforced by gitleaks pre-commit hook)

1. No nested repos. Don't commit other complete project trees inside this one.
2. No secrets. Never commit .secrets/, .env, *.pem, *.key, *.crt, cookie jars.
3. No data blobs. Don't commit *.zip, *.parquet, model weights, sqlite files.
4. No broken files. Shell heredoc accidents must be caught before commit.
5. No duplicate scaffolds. If a backend/ or frontend/ subdir exists at root, it's either THE app or bloat — investigate before adding more.

See CLEANUP.md for cleanup history.

---

AGENTS.md — rmi-backend

Every AI agent working on backend code reads this first.

Last updated: 2026-07-07

What This Is

rmi-backend — FastAPI crypto intelligence backend. 466+ API routes, 200+ MCP tools, 89+ DataBus chains, 39.4M wallet labels (ClickHouse), 20+ SENTINEL scanner modules.

Before You Start

Read these files in order:

1. ~/AGENTS.md — fleet-wide contract, product table, git policy
2. ~/CONVENTIONS.md — shared patterns (coding, naming, testing)
3. ./AGENTS.md (this) — backend-specific instructions
4. ./README.md — full project overview
5. ~/STANDARDS.md — linting, testing, quality gates
6. ~/TOOLCHAIN.md — developer tool inventory

The Server

ALL source edits happen on Talos in the Forgejo clone:

ssh netcup
cd /srv/work/repos/rmi-backend

Deploy artifacts are built from this repo and run on Talos at /root/backend/ (compose, data volumes, .secrets/). The running rmi-backend container is built from the Forgejo image — do not edit code in /root/backend/.

Quick health checks on Talos:

docker logs rmi-backend --tail 100
docker restart rmi-backend
curl localhost:8000/health

Testing

Local (development):

pytest tests/unit/ -q -m "not integration"
pytest tests/unit/test_X.py -q

In the deployed container (when you need full runtime deps):

docker exec rmi-backend pytest -p no:pytest-brownie -v

The -p no:pytest-brownie is mandatory — eth-brownie tries to connect to ganache.

Linting

ruff check app/ tests/
ruff format app/ tests/
make mypy-gate          # scoped gate for clean modules
make typecheck          # full codebase, informational only

MCP Tools

mcp_discover, status_check, analytics_query, wallet_labels, eth_labels_tool, token_security, scam_intel, news_search, rag_query, report_generate, x402_marketplace (+ 200 more)

List: GET /mcp/tools Call: POST /mcp/call/{tool_id} Info: GET /mcp/info

Adding a New Scanner Module

1. Create app/domains/scanners/my_detector.py (fetches from first-party APIs only)
2. Wire it into app/domains/scanners/sentinel_pipeline.py or the relevant orchestrator
3. Add endpoint/tool registration in app/domains/x402/router.py or app/routers/
4. Add pricing to app/domains/billing/x402/config.py if it is a paid tool

CRITICAL: Never call our own x402 endpoints internally.

Adding a New DataBus Chain

1. Create provider function in app/domains/databus/providers/<category>.py
2. Register it in app/domains/databus/providers/chains.py
3. Re-export from app.domains.databus.providers if it is public

x402 Payment Facilitators

Facilitator selection is dynamic and driven by app/domains/billing/x402/config.py and the app.domains.x402 router. Historic docstring claims about a fixed number of "active" or "offline" facilitators are not authoritative; the current supported networks and tokens are defined in code and deployment config.

Rules

1. All data through DataBus — never call providers directly
2. Type everything — Pydantic v2 + mypy strict
3. Async for all I/O — httpx.AsyncClient, asyncpg, asyncio
4. Never bare except — always log + re-raise
5. Use env vars — never hardcode hosts or secrets
6. Add tests for new code — coverage > 80%
7. Conventional commits — feat:/fix:/chore:/docs:/refactor:/test:
8. No secrets in git — vault.py is the only storage
9. No circular API calls — scanner modules don't call our own endpoints
10. Don't add to main.py (28 lines, by design) — use app/mount.py

Git

Internal primary: ssh://git@git.rugmunch.io:2222/RugMunchMedia/rmi-backend Push feat/scanners-p4-8-cont (and other feature branches) on every commit.

External remotes: Codeberg, GitLab (GitHub is currently disabled — account flagged 2026-07-06).