How agent-thor/governance-trading-agent works
Project Type and Purpose
• This is a domain-specific, full-stack automated trading agent for cryptocurrency governance proposals.
• It ingests proposals, runs sentiment and summarization models, makes trading decisions, executes orders on an exchange, persists data in databases, exposes a REST API, and sends notifications (e.g., Slack).
Top-Level Component Analysis
• Entry Points
• main.py / __main__.py – CLI/daemon launcher
• setup.py / install.sh – installation and packaging
• API Layer (api/)
• Exposes REST endpoints (e.g., management of trades, proposals)
• Uses api/dynamo_utils.py for direct DynamoDB access
• Core Business Logic (core/)
• trade_logic.py – encapsulates decision‐making rules
• delete_live_trade.py – housekeeping of active trades
• Data Ingestion / Adapters
• download_models.py – initial model setup
• examples/ – sample usage of data providers
• database/scan_proposal.py & database/mongo_provider.py – support for multiple DB backends
• api or database/dynamo_utils.py – DynamoDB adapter
• Exchange Integration (exchange/)
• binance_api.py – order placement, market data fetch
• price_monitor.py – live price stream & triggers
• open_stop.py – stop‐loss / take‐profit logic
• coin.json & precision.json – instrument metadata
• Models (models/)
• sentiment.py, summarization.py, reasoning.py
• Domain-specific price models (bullish_price.py, bearish_price.py)
• Services (services/)
• slack_bot.py – Slack notifications of decisions / errors
• Utilities (utils/)
• Logging, configuration loader, time formatting, HTML cleaning
• Persistence Layer (database/)
• MongoDB & DynamoDB providers
• Tests (tests/) – unit tests for data provider factory
Data Flow & Component Interactions
• External Inputs
• Governance proposal sources (via HTTP, Firebase, etc.)
• Market data feed (exchange API)
• Ingestion & Storage
• Data adapter reads proposals → database/ (Mongo/Dynamo)
• Processing Pipeline
• Core logic loads proposals → runs through models/ (summarization, sentiment)
• Decision engine (core/trade_logic.py) produces trade signals
• Execution
• Trade signals → exchange/binance_api.py to place orders
• Price monitoring & stops via exchange/price_monitor.py + open_stop.py
• Persistence & Notifications
• Store executed trade record (utils/save_trades.py)
• Send Slack alerts (services/slack_bot.py)
• External API
• Expose endpoints (api/) for querying trades or forcing actions
Architectural Patterns & Principles
• Layered Architecture:
• Presentation/API → Business Logic → Data Access → External Services
• Single Responsibility:
• Each module (e.g., trade_logic.py, slack_bot.py) has one clear role
• Adapter Pattern:
• Multiple database implementations (Mongo vs. Dynamo)
• Exchange abstraction via binance_api.py
a. Components
• External Sources (Governance Feed, Exchange Market Data)
• Data Adapters (inside database/ & api/)
• Core Engine (sentiment & summarization models + trade_logic)
• Exchange Client (Binance API wrapper)
• Persistence (MongoDB, DynamoDB)
• Notification Service (Slack)
• REST API Layer
b. Relationships & Data Flow
• Bidirectional where appropriate (e.g., API calls, DB reads)
c. Technologies & Frameworks
• Python 3, FastAPI (if used in api/), Boto3 (DynamoDB), PyMongo, Ollama (for model serving)
• Docker or virtualenv (implied by install.sh, requirements.txt)
d. Important Patterns
• Adapter pattern for DB & exchange
• Pipeline pattern for data processing and ML inference
Diagramming Conventions
• Blue for Core/Processing
• Green for Data Stores
• Orange for External Services (Exchange, Slack)
• Grey for Setup/Install steps
• Rectangles for modules/components