badboydemo/kairos

Purpose and Entry Points

Kairos is a Telegram-first trading automation platform: it converts unstructured group signals into structured trades, applies deterministic risk controls, and either requests user confirmation or executes through a broker. The deployable services are the FastAPI backend at KAIROS - the product/backend/app/main.py and the persistent Telethon listener at KAIROS - the product/listener/main.py. Container topology is defined in KAIROS - the product/docker-compose.yml.

Signal Ingestion and Queue Boundary

The listener joins signal groups using a user session, manages sessions, and deduplicates incoming Telegram messages before pushing work to Redis. This deliberately separates long-lived Telegram connectivity from backend deployments. Primary paths: KAIROS - the product/listener/main.py, KAIROS - the product/listener/session_manager.py, KAIROS - the product/listener/dedup.py. The backend consumes and assembles queued signal fragments through KAIROS - the product/backend/app/queue/redis_consumer.py and KAIROS - the product/backend/app/queue/signal_assembly.py.

Signal Interpretation and Routing

The signal domain parses messages, including Aurum/Pine-originated signals, then routes valid structured signals into the trade flow. Core paths: KAIROS - the product/backend/app/signals/service.py, KAIROS - the product/backend/app/signals/parser.py, KAIROS - the product/backend/app/signals/router.py. Hermes can contribute AI-based signal interpretation through KAIROS - the product/backend/app/hermes/agents/signal_intelligence.py; Claude/Anthropic is an external parsing dependency, not the authorization point.

Risk Gate and Trade Execution

The risk engine is the hard execution boundary: it calculates sizing and evaluates limits or halt conditions before a trade can proceed. Core paths: KAIROS - the product/backend/app/risk/engine.py, KAIROS - the product/backend/app/risk/sizing.py, KAIROS - the product/backend/app/risk/halt.py. Approved manual and automatic flows converge in KAIROS - the product/backend/app/trades/service.py and KAIROS - the product/backend/app/trades/executor.py, which execute via MetaApi. Broker connection pooling, synchronization, degradation, and reconciliation are isolated in KAIROS - the product/backend/app/brokers/pool.py, KAIROS - the product/backend/app/brokers/sync_listener.py, and KAIROS - the product/backend/app/brokers/reconciliation.py.

Telegram Interaction and Onboarding

Telegram is both the operational UI and callback ingress: the bot/webhook handles confirmations and notifications, while onboarding provisions identity, groups, broker connectivity, and risk preferences. Paths: KAIROS - the product/backend/app/telegram/webhook.py, KAIROS - the product/backend/app/telegram/bot.py, KAIROS - the product/backend/app/onboarding/dispatch.py. Notifications are emitted through KAIROS - the product/backend/app/notifications/dispatch.py.

Hermes Intelligence Layer

Hermes is the internal multi-agent orchestration layer for conversation, command handling, contextual reasoning, risk-oriented guidance, and trading management. The routing/control plane is in KAIROS - the product/backend/app/hermes/agent_manager.py, KAIROS - the product/backend/app/hermes/agents/orchestrator.py, and KAIROS - the product/backend/app/hermes/conversation_engine.py. Its model router abstracts provider selection, policy, fallback, cache payloads, metrics, and alerts: KAIROS - the product/backend/app/hermes/model_router/router.py, KAIROS - the product/backend/app/hermes/model_router/policy.py.

State, Tenancy, and Durable Memory

Supabase/Postgres is the durable system of record for users, groups, broker accounts, trades, rules, sessions, billing, notifications, and Hermes memory. Database access and tenant scoping reside in KAIROS - the product/backend/app/db/client.py, KAIROS - the product/backend/app/db/scoping.py, with schema evolution in KAIROS - the product/supabase/migrations/0001_init_schema.sql through KAIROS - the product/supabase/migrations/0012_memory_weaver.sql. Hermes memory is managed by KAIROS - the product/backend/app/hermes/memory_manager.py; the separate Memory Weaver synchronizes knowledge to Git/Obsidian via KAIROS - the product/backend/app/memory_weaver/sync.py.

Runtime and External Infrastructure

The runtime is Python/FastAPI plus Redis, Docker Compose, and Nginx reverse proxy configuration at KAIROS - the product/infra/nginx/kairos.conf. External services are Telegram (Bot API and Telethon API), Supabase, Anthropic, and MetaApi/broker accounts. Billing and subscription enforcement are backend concerns in KAIROS - the product/backend/app/billing/limits.py, KAIROS - the product/backend/app/billing/metering.py, and KAIROS - the product/backend/app/billing/webhook.py.