diff --git a/.env.example b/.env.example index a2eeff6d..5b68f78b 100644 --- a/.env.example +++ b/.env.example @@ -1,12 +1,30 @@ -# Kalshi Trading API (Required) -KALSHI_API_KEY_ID=your_kalshi_key_id -KALSHI_API_KEY=your_kalshi_api_key +# ============================================ +# NEURAL SDK - ENVIRONMENT TEMPLATE +# ============================================ +# Copy this file to .env and fill in your actual values -# OpenWeatherMap API (Working!) -OPENWEATHER_API_KEY=78596505b0f5fea89e98ebcbf3bd6e21 +# --- NEURAL API (Required) --- +# Accepts: prod | demo (used for Kalshi endpoints) +NEURAL_ENVIRONMENT=prod +NEURAL_API_KEY_ID=your_neural_api_key_id +# Either provide the private key INLINE or via FILE path +# NEURAL_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" +NEURAL_PRIVATE_KEY_FILE=./keys/neural_prod_private.key -# Reddit API (Optional - for sentiment analysis) +# --- EXTERNAL APIs --- +# Used by weather adapter (config/data_sources.yaml) +OPENWEATHER_API_KEY=your_openweather_api_key REDDIT_CLIENT_ID=your_reddit_client_id REDDIT_CLIENT_SECRET=your_reddit_client_secret -# DraftKings (No API key needed - public data) \ No newline at end of file +# --- LLM CONFIGURATION --- +OPENROUTER_API_KEY=your_openrouter_api_key + +# --- OTHER SERVICES --- +E2B_API_KEY=your_e2b_api_key +EXA_API_KEY=your_exa_api_key +TWITTERAPI_KEY=your_twitter_api_key + +# --- AGENTUITY PLATFORM --- +AGENTUITY_SDK_KEY=your_agentuity_sdk_key +AGENTUITY_PROJECT_KEY=your_agentuity_project_key diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c7282d82..bd0189ae 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -104,7 +104,7 @@ jobs: - name: Install package run: | pip install dist/*.whl - python -c "import agent_consumers; print('โœ… Package imported successfully')" + python -c "import sdk, data_pipeline; print('โœ… Package imported successfully')" create-github-release: name: Create GitHub Release @@ -263,4 +263,4 @@ jobs: - name: Create incident run: | echo "๐Ÿ“ Creating incident report" - # gh issue create --title "Production deployment failed: ${{ needs.validate-version.outputs.version }}" --body "Automatic rollback initiated" \ No newline at end of file + # gh issue create --title "Production deployment failed: ${{ needs.validate-version.outputs.version }}" --body "Automatic rollback initiated" diff --git a/.gitignore b/.gitignore index e4796dd1..518d5f7f 100644 --- a/.gitignore +++ b/.gitignore @@ -131,6 +131,9 @@ celerybeat.pid .env .env.development .env.production +.env.demo +.env.* +!*.example .venv env/ venv/ @@ -191,6 +194,7 @@ keys/ # Project Specific logs/ *.log +data/ data/cache/ data/backtest_results/ temp/ @@ -214,4 +218,4 @@ Thumbs.db # Test outputs test_results/ coverage/ -.pytest_cache/ \ No newline at end of file +.pytest_cache/ diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 2ea1bbdd..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,494 +0,0 @@ -# CLAUDE.md - -This file provides comprehensive guidance to Claude Code (claude.ai/code) when working with the Kalshi Trading Agent System. - -## Project Overview - -Autonomous multi-agent trading system for Kalshi sports event contracts using the Agentuity framework. The system uses real-time WebSocket streams, Redis pub/sub for data distribution, and sophisticated agents with LLM analysis to execute trades using the Kelly Criterion for optimal position sizing. - -## System Architecture - -### Data Flow Pipeline -``` -[External APIs] โ†’ [WebSocket Streams] โ†’ [Redis Pub/Sub] โ†’ [Agent Consumers] โ†’ [Trading Decisions] - โ†“ โ†“ โ†“ - [Stream Manager] [Event Publisher] [Agentuity Agents] - โ†“ โ†“ โ†“ - [Reliability Layer] [Redis Channels] [Kalshi API] -``` - -### Directory Structure (Production Names) -``` -. -โ”œโ”€โ”€ agents/ # Agentuity platform agents (high-level logic) -โ”œโ”€โ”€ agent_consumers/ # Redis consumers (data processing) -โ”œโ”€โ”€ data_pipeline/ # Data ingestion and streaming -โ”‚ โ”œโ”€โ”€ orchestration/ # Stream coordination -โ”‚ โ”œโ”€โ”€ streaming/ # WebSocket clients -โ”‚ โ”œโ”€โ”€ data_sources/ # API integrations -โ”‚ โ””โ”€โ”€ reliability/ # Resilience components -โ”œโ”€โ”€ trading_logic/ # Trading algorithms and tools -โ”œโ”€โ”€ tests/ # Test suite -โ”œโ”€โ”€ examples/ # Usage examples -โ””โ”€โ”€ docs/ # Documentation -``` - -## Key Design Decisions - -### 1. Redis Pub/Sub Architecture -**Decision:** Use Redis as central message broker -**Rationale:** -- Decouples data sources from consumers -- Enables horizontal scaling -- Provides buffering and persistence -- Supports multiple subscribers per channel - -### 2. Separation of Concerns -**Decision:** Split agents into consumers and platform agents -**Rationale:** -- `agent_consumers/`: Handle real-time data, no LLM calls -- `agents/`: Complex decisions with LLM analysis -- Clear performance boundaries -- Easier testing and debugging - -### 3. Kelly Criterion with Safety Factor -**Decision:** Use 25% of Kelly for position sizing -**Rationale:** -- Reduces risk of ruin -- Accounts for estimation errors -- Provides smoother equity curve -- Industry standard practice - -## Common Development Tasks - -### Adding a New Data Source - -1. **Create WebSocket Client** -```python -# data_pipeline/streaming/new_source.py -class NewSourceWebSocket: - async def connect(self): - # Implementation - - async def subscribe(self, channels): - # Implementation -``` - -2. **Add to Stream Manager** -```python -# data_pipeline/orchestration/unified_stream_manager.py -self.new_source_client = NewSourceWebSocket(config) -await self.new_source_client.connect() -``` - -3. **Define Redis Channel** -```python -# data_pipeline/orchestration/redis_event_publisher.py -await self.publish("newsource:events", event_data) -``` - -4. **Create Consumer** -```python -# agent_consumers/NewConsumer/consumer.py -class NewConsumer(BaseConsumer): - async def process_message(self, channel, data): - # Process events -``` - -### Implementing a Trading Strategy - -1. **Define Strategy in Agent** -```python -# agents/StrategyAnalyst/agent.py -@tool -def analyze_opportunity(market_data, sentiment): - # Strategy logic - return signal -``` - -2. **Process Signals in Consumer** -```python -# agent_consumers/DataCoordinator/data_coordinator.py -if signal.strength > THRESHOLD: - await self.publish_signal(signal) -``` - -3. **Execute Trade** -```python -# agents/TradeExecutor/agent.py -@tool -def execute_trade(signal): - position_size = calculate_kelly_position(signal) - order = place_order(market, side, position_size) - return order -``` - -### Testing Workflows - -1. **Test Redis Integration** -```bash -# Start Redis -redis-server - -# Run integration tests -pytest tests/test_redis_integration.py -``` - -2. **Test Individual Agent** -```bash -# Start in dev mode -agentuity dev - -# Test specific agent -agentuity agent test DataCoordinator -``` - -3. **Full System Test** -```bash -# Run all components -python examples/agent_redis_consumer.py all -``` - -## Code Style & Conventions - -### Python Standards -- Use Python 3.10+ features -- Type hints for all functions -- Async/await for I/O operations -- Dataclasses for data structures - -### Naming Conventions -```python -# Files and modules: snake_case -unified_stream_manager.py - -# Classes: PascalCase -class DataCoordinator: - pass - -# Functions and variables: snake_case -def calculate_position_size(): - pass - -# Constants: UPPER_SNAKE_CASE -MAX_POSITION_SIZE = 100 -``` - -### Import Organization -```python -# Standard library -import os -import asyncio -from datetime import datetime - -# Third-party -import redis -import websockets -from agentuity import Agent, tool - -# Local application -from data_pipeline.orchestration import StreamManager -from agent_consumers.base_consumer import BaseConsumer -from trading_logic.kelly_tools import calculate_kelly -``` - -### Error Handling Pattern -```python -async def robust_operation(): - """Standard error handling pattern.""" - max_retries = 3 - retry_delay = 1.0 - - for attempt in range(max_retries): - try: - result = await risky_operation() - return result - except TemporaryError as e: - logger.warning(f"Attempt {attempt + 1} failed: {e}") - if attempt < max_retries - 1: - await asyncio.sleep(retry_delay) - retry_delay *= 2 # Exponential backoff - else: - raise - except PermanentError as e: - logger.error(f"Permanent failure: {e}") - raise -``` - -## Trading Logic Implementation - -### Position Sizing -Always use Kelly Criterion with safety factors: -```python -# Never use full Kelly -position = kelly_fraction * 0.25 # 25% of Kelly - -# Apply hard limits -position = min(position, MAX_POSITION_SIZE) -position = max(position, MIN_POSITION_SIZE) - -# Check portfolio exposure -if total_exposure + position > MAX_PORTFOLIO_EXPOSURE: - position = MAX_PORTFOLIO_EXPOSURE - total_exposure -``` - -### Risk Management Rules -1. **Stop Loss**: Always set at order time -2. **Position Limits**: Max 5% per position -3. **Correlation**: Reduce size for correlated bets -4. **Drawdown**: Stop at 20% daily loss - -### Market Analysis -```python -# Check for arbitrage -if yes_price + no_price < 0.98: - # Arbitrage opportunity exists - -# Check liquidity -if volume < MIN_LIQUIDITY: - # Skip illiquid markets - -# Check spread -if abs(yes_price - no_price) > MAX_SPREAD: - # Market too wide -``` - -## Performance Considerations - -### WebSocket Management -- Maintain persistent connections -- Implement heartbeat/ping -- Buffer during disconnections -- Automatic reconnection - -### Redis Optimization -- Use connection pooling -- Batch publish when possible -- Set appropriate TTLs -- Monitor memory usage - -### Agent Performance -- Cache LLM responses -- Batch similar requests -- Use appropriate models -- Monitor token usage - -## Security Practices - -### API Keys -```bash -# Never hardcode keys -KALSHI_API_KEY_ID=xxx # In .env file - -# Use environment variables -key_id = os.getenv("KALSHI_API_KEY_ID") -``` - -### Data Privacy -- Don't log sensitive data -- Sanitize user inputs -- Encrypt stored credentials -- Audit access logs - -## Troubleshooting Guide - -### Common Issues - -#### WebSocket Disconnections -```python -# Check: Connection status -logger.info(f"WebSocket state: {ws.state}") - -# Solution: Automatic reconnection -await exponential_backoff_retry() -``` - -#### Redis Pub/Sub Issues -```bash -# Check: Redis connectivity -redis-cli ping - -# Check: Active subscriptions -redis-cli PUBSUB CHANNELS - -# Monitor: Message flow -redis-cli MONITOR -``` - -#### No Trading Signals -```python -# Check: Data pipeline -assert stream_manager.is_connected() - -# Check: Agent consumers -assert len(active_consumers) > 0 - -# Check: Signal thresholds -logger.info(f"Signal threshold: {SIGNAL_THRESHOLD}") -``` - -#### High Latency -```bash -# Profile: Message processing -python -m cProfile -s cumulative server.py - -# Check: Redis performance -redis-cli --latency - -# Monitor: System resources -htop -``` - -## Deployment Checklist - -### Pre-Deployment -- [ ] All tests passing -- [ ] Environment variables set -- [ ] Redis configured -- [ ] API credentials valid -- [ ] Risk limits configured - -### Deployment Steps -```bash -# 1. Set production environment -export ENVIRONMENT=production - -# 2. Verify configuration -agentuity config verify - -# 3. Deploy agents -agentuity deploy - -# 4. Monitor logs -agentuity logs --follow -``` - -### Post-Deployment -- [ ] Verify WebSocket connections -- [ ] Check Redis pub/sub -- [ ] Confirm agent health -- [ ] Monitor first trades -- [ ] Review error logs - -## Performance Benchmarks - -### Expected Metrics -- WebSocket latency: < 100ms -- Redis publish: < 10ms -- Agent processing: < 500ms -- End-to-end: < 1 second - -### Capacity Planning -- Redis: 10K messages/second -- WebSocket: 1K updates/second -- Agents: 100 decisions/minute -- Trades: 20 per day maximum - -## Emergency Procedures - -### Market Halt -```python -# Immediate stop -await risk_manager.emergency_stop() - -# Cancel all orders -await trade_executor.cancel_all_orders() - -# Notify team -await send_alert("Trading halted") -``` - -### Data Loss -```python -# Switch to cached data -await use_fallback_data() - -# Reduce position sizes -KELLY_FRACTION *= 0.5 - -# Log incident -logger.critical("Data loss detected") -``` - -## Testing Strategy - -### Unit Tests -Test individual components in isolation: -```bash -pytest tests/unit/ -v -``` - -### Integration Tests -Test component interactions: -```bash -pytest tests/integration/ -v -``` - -### End-to-End Tests -Test full system flow: -```bash -pytest tests/e2e/ -v -``` - -### Performance Tests -```bash -# Load testing -locust -f tests/load/locustfile.py - -# Stress testing -python tests/stress/stress_test.py -``` - -## Important Notes - -### Do's -- โœ… Always use try/except for external calls -- โœ… Log all trading decisions -- โœ… Validate data before processing -- โœ… Use type hints -- โœ… Write tests for new features - -### Don'ts -- โŒ Never commit secrets -- โŒ Don't bypass risk checks -- โŒ Avoid synchronous I/O -- โŒ Don't ignore error logs -- โŒ Never use full Kelly - -## Quick Commands Reference - -```bash -# Development -agentuity dev # Start dev server -uv run server.py # Run directly -uv run pytest tests/ # Run tests - -# Redis -redis-cli ping # Check Redis -redis-cli MONITOR # Monitor messages -redis-cli FLUSHALL # Clear all data - -# Deployment -agentuity deploy # Deploy to cloud -agentuity logs DataCoordinator # View agent logs -agentuity status # Check deployment - -# Monitoring -python examples/agent_redis_consumer.py all # Run all consumers -python examples/test_kalshi_websocket.py # Test WebSocket -``` - -## Contact & Support - -For questions about: -- **Architecture**: Review docs/ARCHITECTURE.md -- **Agents**: Check agents/README.md -- **Trading Logic**: See trading_logic/README.md -- **Data Pipeline**: Read data_pipeline/README.md - -When debugging: -1. Check logs first -2. Verify configuration -3. Test components individually -4. Review recent changes -5. Check system resources \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..50b37a1b --- /dev/null +++ b/Dockerfile @@ -0,0 +1,25 @@ +FROM python:3.11-slim + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 + +RUN apt-get update \ + && apt-get install -y --no-install-recommends curl build-essential \ + && rm -rf /var/lib/apt/lists/* + +# Optional: install uv for reproducible installs +RUN curl -LsSf https://astral.sh/uv/install.sh | sh && ln -s /root/.local/bin/uv /usr/local/bin/uv + +WORKDIR /app + +# Install dependencies first (leverage caching) +COPY pyproject.toml uv.lock ./ +RUN uv sync --no-dev || pip install . + +# Copy source and configs +COPY neural_sdk ./neural_sdk +COPY config ./config + +# Default command does a smoke import +CMD ["python", "-c", "import neural_sdk; print('Neural SDK OK')"] + diff --git a/INVESTOR_DEMO.md b/INVESTOR_DEMO.md deleted file mode 100644 index c57cb5f4..00000000 --- a/INVESTOR_DEMO.md +++ /dev/null @@ -1,496 +0,0 @@ -# ๐Ÿ† Kalshi Trading Agent Platform -## AI-Powered Sports Prediction Market Trading System - ---- - -## Executive Summary - -### ๐Ÿ“Š The Opportunity -- **$2B+ Daily Volume** in sports prediction markets -- **67% Average Spread** indicates market inefficiencies -- **<100ms Latency Advantage** over manual traders -- **24/7 Autonomous Operation** capturing opportunities humans miss - -### ๐ŸŽฏ Our Solution -An institutional-grade autonomous trading system that: -- Correlates real-time game data with market prices -- Uses AI to identify and exploit pricing inefficiencies -- Manages risk using proven quantitative methods -- Scales horizontally to trade hundreds of markets simultaneously - ---- - -## System Architecture Overview - -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ KALSHI TRADING AGENT PLATFORM โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ โ”‚ -โ”‚ DATA INGESTION LAYER โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ Kalshi โ”‚ โ”‚ ESPN โ”‚ โ”‚ Twitter โ”‚ โ”‚ -โ”‚ โ”‚ WebSocket โ”‚ โ”‚ Stream โ”‚ โ”‚ Sentiment โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ -โ”‚ โ•โ•โ•โ•โ•โ•โ•โ•ชโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ชโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ชโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• โ”‚ -โ”‚ โ–ผ โ–ผ โ–ผ โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ UNIFIED STREAM MANAGER โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Event Correlation โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Time Synchronization โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Backpressure Control โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ โ”‚ -โ”‚ DISTRIBUTION LAYER โ–ผ โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ REDIS PUB/SUB HUB โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข 10K msg/sec throughput โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Channel-based routing โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Persistent message buffer โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ -โ”‚ INTELLIGENCE LAYER โ”‚ -โ”‚ โ–ผ โ–ผ โ–ผ โ–ผ โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚Data โ”‚ โ”‚Marketโ”‚ โ”‚Risk โ”‚ โ”‚Trade โ”‚ โ”‚ -โ”‚ โ”‚Coord.โ”‚ โ”‚Analy.โ”‚ โ”‚Mgr. โ”‚ โ”‚Exec. โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ -โ”‚ EXECUTION LAYER โ”‚ โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ โ”‚ -โ”‚ โ–ผ โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ KALSHI API โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Orders โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Positions โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - ---- - -## ๐Ÿš€ Live Data Flow Demonstration - -### Real-Time Market Monitoring -```python -# LIVE EXAMPLE: Super Bowl 2025 - Chiefs vs Bills -Market: SUPERBOWL-2025-WINNER -Current Prices: Chiefs YES: $0.65 | Bills YES: $0.35 - -๐Ÿ“ˆ Data Sources Active: -- Kalshi WebSocket: โœ… Connected (12ms latency) -- ESPN GameCast: โœ… Streaming (45ms latency) -- Twitter Sentiment: โœ… Processing (2,341 tweets/min) - -๐Ÿ”„ Recent Events (Last 30 seconds): -[14:23:45] ESPN: Touchdown Chiefs! Score: 21-14 -[14:23:46] Twitter: Sentiment spike detected (+18% Chiefs) -[14:23:47] Kalshi: Price movement $0.62 โ†’ $0.65 (+4.8%) -[14:23:48] System: OPPORTUNITY - Market lagging game event -[14:23:49] Trade: BUY Chiefs YES @ $0.65 (100 contracts) -[14:23:51] Trade: FILLED @ $0.65 โœ“ - -๐Ÿ’ฐ P&L This Session: +$487.23 (12 trades, 83% win rate) -``` - ---- - -## ๐Ÿง  AI Agent Architecture - -### Always-On Agents (24/7 Monitoring) -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ DATA COORDINATOR AGENT โ”‚ -โ”‚ โ€ข Correlates multi-source data โ”‚ -โ”‚ โ€ข Maintains market context โ”‚ -โ”‚ โ€ข Publishes unified events โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” - โ–ผ โ–ผ โ–ผ -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚Portfolioโ”‚ โ”‚ Market โ”‚ โ”‚ Risk โ”‚ -โ”‚ Monitor โ”‚ โ”‚ Scanner โ”‚ โ”‚ Monitor โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - -### On-Demand Agents (Decision Making) -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ STRATEGY ANALYST AGENT โ”‚ -โ”‚ โ€ข GPT-4 powered analysis โ”‚ -โ”‚ โ€ข Pattern recognition โ”‚ -โ”‚ โ€ข Probability calculation โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ - โ–ผ -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ TRADE EXECUTOR AGENT โ”‚ -โ”‚ โ€ข Kelly Criterion sizing โ”‚ -โ”‚ โ€ข Order management โ”‚ -โ”‚ โ€ข Execution optimization โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - ---- - -## ๐Ÿ“Š Backtesting & Performance - -### Historical Performance (2024 Season) -``` -Period: Jan 2024 - Dec 2024 -Markets Traded: 487 -Total Trades: 3,241 - -Performance Metrics: -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ Sharpe Ratio: 2.87 โ”‚ -โ”‚ Win Rate: 67.3% โ”‚ -โ”‚ Avg Win/Loss: 1.82 โ”‚ -โ”‚ Max Drawdown: -12.4% โ”‚ -โ”‚ Total Return: +187% โ”‚ -โ”‚ Profit Factor: 2.41 โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - -Monthly Returns: -Jan: +14.2% Apr: +11.8% Jul: +18.3% Oct: +22.1% -Feb: +8.7% May: +15.4% Aug: +12.9% Nov: +19.7% -Mar: +9.3% Jun: -3.2% Sep: +16.5% Dec: +24.8% -``` - -### Strategy Optimization Results -```python -# Genetic Algorithm Optimization (10,000 iterations) -OPTIMAL PARAMETERS: -โ”œโ”€โ”€ Kelly Multiplier: 0.25 (25% of full Kelly) -โ”œโ”€โ”€ Stop Loss: 12% -โ”œโ”€โ”€ Take Profit: 35% -โ”œโ”€โ”€ Min Edge Required: 3.5% -โ”œโ”€โ”€ Confidence Threshold: 0.72 -โ””โ”€โ”€ Max Position Size: 5% of capital - -# Walk-Forward Analysis (6 months out-of-sample) -In-Sample Sharpe: 2.87 -Out-of-Sample Sharpe: 2.64 โœ“ (Robust) -``` - ---- - -## ๐Ÿ›ก๏ธ Risk Management - -### Multi-Layer Risk Control -``` -Level 1: Pre-Trade Checks -โ”œโ”€โ”€ Market liquidity verification -โ”œโ”€โ”€ Correlation analysis -โ”œโ”€โ”€ Position sizing (Kelly Criterion) -โ””โ”€โ”€ Max exposure limits - -Level 2: Real-Time Monitoring -โ”œโ”€โ”€ Stop-loss triggers -โ”œโ”€โ”€ Drawdown circuit breakers -โ”œโ”€โ”€ Volatility adjustment -โ””โ”€โ”€ Portfolio heat mapping - -Level 3: System Protection -โ”œโ”€โ”€ API rate limiting -โ”œโ”€โ”€ Connection redundancy -โ”œโ”€โ”€ Data validation -โ””โ”€โ”€ Emergency shutdown -``` - -### Live Risk Dashboard -``` -Current Portfolio Status: -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -Open Positions: 8 -Total Exposure: $24,531 (49% of capital) -Daily P&L: +$1,247 (+2.5%) -Risk Metrics: - โ€ข VaR (95%): $1,823 - โ€ข Correlation Risk: LOW - โ€ข System Health: 98/100 -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” -``` - ---- - -## ๐Ÿ’ป Technology Stack - -### Core Infrastructure -- **Language**: Python 3.11+ with async/await -- **Message Queue**: Redis Pub/Sub (10K msg/sec) -- **WebSockets**: Persistent bi-directional streams -- **AI/ML**: OpenAI GPT-4, Custom sentiment models -- **Monitoring**: Prometheus + Grafana dashboards - -### Performance Specifications -``` -Latency Benchmarks: -โ”œโ”€โ”€ Market Data โ†’ Decision: <100ms -โ”œโ”€โ”€ Decision โ†’ Execution: <50ms -โ”œโ”€โ”€ End-to-End: <200ms -โ””โ”€โ”€ Failure Recovery: <2 seconds - -Capacity: -โ”œโ”€โ”€ Concurrent Markets: 500+ -โ”œโ”€โ”€ Events/Second: 10,000 -โ”œโ”€โ”€ Decisions/Minute: 100 -โ””โ”€โ”€ Orders/Day: 1,000+ -``` - ---- - -## ๐Ÿ“ˆ Competitive Advantages - -### 1. **Speed** - Microsecond Advantage -``` -Human Trader: 2-5 seconds to react -Our System: 0.1 seconds to execute -Advantage: 20-50x faster -``` - -### 2. **Scale** - Parallel Processing -``` -Human: Monitors 1-3 markets -System: Monitors 500+ markets -Advantage: 166x coverage -``` - -### 3. **Consistency** - No Emotions -``` -Human: 55% win rate (emotional decisions) -System: 67% win rate (data-driven) -Advantage: 22% improvement -``` - -### 4. **Intelligence** - AI Enhancement -```python -# Real correlation example -if espn_touchdown_event and not kalshi_price_moved: - confidence = calculate_edge(game_state, market_state) - if confidence > 0.72: - execute_trade(size=kelly_position(confidence)) -``` - ---- - -## ๐ŸŽฏ Market Opportunity - -### Total Addressable Market -- **Kalshi Daily Volume**: $2M+ and growing -- **Sports Betting Market**: $150B globally -- **Prediction Markets**: $10B+ by 2025 - -### Revenue Model -- **Performance Fee**: 20% of profits -- **Management Fee**: 2% AUM -- **License Revenue**: White-label to funds - -### Scalability Path -``` -Phase 1: Single Exchange (Kalshi) โœ“ Complete -Phase 2: Multi-Exchange (Polymarket, Manifold) -Phase 3: Traditional Sports Books Integration -Phase 4: Custom Market Making -``` - ---- - -## ๐Ÿšฆ Live System Demo - -### Starting the Platform -```bash -# Initialize all components -$ python scripts/run_agents.py all - -[2024-08-30 14:30:00] Starting Kalshi Trading Platform... -[2024-08-30 14:30:01] โœ“ Redis connected (localhost:6379) -[2024-08-30 14:30:02] โœ“ Kalshi WebSocket connected -[2024-08-30 14:30:03] โœ“ ESPN stream active (4 games) -[2024-08-30 14:30:04] โœ“ Twitter sentiment analyzer online -[2024-08-30 14:30:05] โœ“ 5 AI agents initialized -[2024-08-30 14:30:06] โœ“ Risk manager active -[2024-08-30 14:30:07] System ready. Monitoring 12 markets... - -โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• - KALSHI TRADING PLATFORM - LIVE -โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• -Markets: 12 | Agents: 5 | Latency: 23ms -P&L Today: +$1,247.83 | Win Rate: 71% -โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• -``` - -### Real-Time Market Action -```python -# Live opportunity detection -[14:31:23] ๐ŸŽฏ OPPORTUNITY DETECTED -Market: NFL-WEEK18-KC-BUF -Signal: BIG_PLAY_DIVERGENCE -โ”œโ”€โ”€ ESPN: 75-yard TD pass (Chiefs) -โ”œโ”€โ”€ Twitter: +2,341 mentions/min -โ”œโ”€โ”€ Kalshi: No price movement yet -โ”œโ”€โ”€ Edge: 8.3% (HIGH CONFIDENCE) -โ””โ”€โ”€ Action: BUY 250 contracts @ $0.64 - -[14:31:24] ๐Ÿ“Š Executing Trade... -โ”œโ”€โ”€ Kelly Position: $1,250 (2.5% of capital) -โ”œโ”€โ”€ Order ID: ORD-2024-483921 -โ”œโ”€โ”€ Status: PENDING โ†’ FILLED -โ””โ”€โ”€ Fill Price: $0.64 โœ“ - -[14:31:28] ๐Ÿ’ฐ Price Movement -โ”œโ”€โ”€ Market moved: $0.64 โ†’ $0.69 -โ”œโ”€โ”€ Unrealized P&L: +$125.00 -โ””โ”€โ”€ Signal accuracy: CONFIRMED โœ“ -``` - ---- - -## ๐Ÿ“Š Performance Analytics Dashboard - -``` -โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•— -โ•‘ LIVE TRADING DASHBOARD โ•‘ -โ• โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ฃ -โ•‘ โ•‘ -โ•‘ Portfolio Performance (24H) โ•‘ -โ•‘ โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘ +4.7% โ•‘ -โ•‘ โ•‘ -โ•‘ Win Rate by Market Type โ•‘ -โ•‘ NFL: โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘ 72% โ•‘ -โ•‘ NBA: โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘ 65% โ•‘ -โ•‘ MLB: โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘ 68% โ•‘ -โ•‘ โ•‘ -โ•‘ System Health โ•‘ -โ•‘ CPU: โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 23% โ•‘ -โ•‘ MEM: โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 41% โ•‘ -โ•‘ NET: โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 15% โ•‘ -โ•‘ โ•‘ -โ•‘ Active Strategies โ•‘ -โ•‘ โ€ข Momentum Following [ACTIVE] +$823 โ•‘ -โ•‘ โ€ข Mean Reversion [ACTIVE] +$412 โ•‘ -โ•‘ โ€ข Sentiment Arbitrage [ACTIVE] +$198 โ•‘ -โ•‘ โ€ข Event Correlation [PAUSED] $0 โ•‘ -โ•‘ โ•‘ -โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• -``` - ---- - -## ๐Ÿ”ฎ Future Roadmap - -### Q1 2025: Enhanced Intelligence -- [ ] GPT-4 Vision for game footage analysis -- [ ] Custom transformer models for price prediction -- [ ] Reinforcement learning for strategy optimization - -### Q2 2025: Market Expansion -- [ ] Polymarket integration -- [ ] Augur protocol support -- [ ] Cross-market arbitrage - -### Q3 2025: Institutional Features -- [ ] FIX protocol support -- [ ] Multi-account management -- [ ] Compliance reporting - -### Q4 2025: Platform as a Service -- [ ] White-label solution -- [ ] API for third-party strategies -- [ ] Mobile monitoring app - ---- - -## ๐Ÿ’ก Investment Highlights - -### Why Invest Now? -1. **First Mover**: Early in prediction market automation -2. **Proven System**: 187% return in backtesting -3. **Scalable Tech**: Handles 500+ markets simultaneously -4. **Protected IP**: Proprietary correlation algorithms -5. **Growing Market**: 300% YoY growth in prediction markets - -### Use of Funds -``` -$2M Seed Round Allocation: -โ”œโ”€โ”€ 40% - Engineering (ML/AI team expansion) -โ”œโ”€โ”€ 25% - Infrastructure (servers, data feeds) -โ”œโ”€โ”€ 20% - Compliance & Legal -โ”œโ”€โ”€ 10% - Marketing & BD -โ””โ”€โ”€ 5% - Operations -``` - -### Expected Returns -``` -Conservative: 35% annual return -Base Case: 65% annual return -Optimistic: 120% annual return - -With 2% management + 20% performance fee: -Year 1 Revenue: $1.2M -Year 2 Revenue: $4.8M -Year 3 Revenue: $18M -``` - ---- - -## ๐Ÿค Team & Advisors - -### Core Team -- **CTO**: 15 years quantitative trading -- **Head of AI**: Ex-DeepMind, PhD ML -- **Lead Engineer**: Ex-Jane Street -- **Risk Manager**: Ex-Citadel - -### Advisors -- Former Head of Trading, Two Sigma -- Professor of Statistics, MIT -- Early investor in Polymarket - ---- - -## ๐Ÿ“ž Contact & Next Steps - -### Live Demo Available -See the system trade in real-time on actual markets - -### Documentation -- Technical Architecture: `/docs/ARCHITECTURE.md` -- API Documentation: `/docs/API.md` -- Risk Framework: `/docs/RISK_MANAGEMENT.md` - -### Investment Inquiries -Ready to discuss terms and provide deeper technical dive - ---- - -## โšก Quick Start Demo - -```bash -# Clone and setup -git clone [repository] -cd Kalshi_Agentic_Agent - -# Install dependencies -pip install -r requirements.txt - -# Configure credentials -cp .env.example .env -# Add your API keys - -# Run backtesting demo -python scripts/run_backtest.py --mode optimize - -# Start live trading (paper mode) -python scripts/run_agents.py all --paper-trading - -# View real-time dashboard -open http://localhost:8080/dashboard -``` - ---- - -*This platform represents the future of algorithmic trading in prediction markets - combining speed, intelligence, and scale to capture opportunities invisible to human traders.* \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..d0b9fb18 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Kalshi Trading SDK + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/PLATFORM_ROADMAP.md b/PLATFORM_ROADMAP.md deleted file mode 100644 index 341d96c7..00000000 --- a/PLATFORM_ROADMAP.md +++ /dev/null @@ -1,556 +0,0 @@ -# ๐Ÿš€ Neural Trading Platform - Development Roadmap - -## Executive Vision -Transform the Kalshi Trading Agent into a **universal algorithmic trading platform** where users can: -- Plug in any data source (websockets, APIs, databases) -- Deploy custom trading algorithms -- Backtest strategies across multiple markets -- Share and monetize successful strategies - ---- - -## ๐Ÿ“Š Platform Evolution Phases - -### Phase 1: Core Infrastructure (Q1 2025) -**Goal:** Build extensible foundation for custom components - -#### 1.1 Plugin Architecture -```python -# Example: Custom Data Source Plugin -class CustomDataPlugin(BaseDataSource): - """User-defined data source""" - - async def connect(self): - """Connect to custom websocket/API""" - pass - - async def subscribe(self, symbols): - """Subscribe to data streams""" - pass - - def transform(self, raw_data): - """Transform to unified format""" - return UnifiedEvent(...) -``` - -#### 1.2 Strategy Framework -```python -# Example: Custom Trading Strategy -class UserStrategy(BaseStrategy): - """User-defined trading algorithm""" - - def analyze(self, market_data, indicators): - """Custom analysis logic""" - signal = self.calculate_signal(market_data) - return TradingSignal( - action="BUY", - confidence=0.85, - size=self.kelly_sizing(signal) - ) -``` - -#### 1.3 Unified Data Model -```yaml -# Standardized event schema -UnifiedMarketEvent: - timestamp: datetime - source: string - symbol: string - data: - price: float - volume: float - bid: float - ask: float - custom_fields: dict -``` - -**Deliverables:** -- [ ] Plugin system with hot-reload capability -- [ ] Strategy SDK with examples -- [ ] Data transformation pipeline -- [ ] Developer documentation - ---- - -### Phase 2: Developer Platform (Q2 2025) -**Goal:** Enable developers to build and test strategies - -#### 2.1 Visual Strategy Builder -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ STRATEGY BUILDER UI โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ [Data Sources] โ†’ [Indicators] โ†’ โ”‚ -โ”‚ โ†“ โ†“ โ”‚ -โ”‚ [Conditions] โ†’ [Actions] โ”‚ -โ”‚ โ†“ โ†“ โ”‚ -โ”‚ [Risk Rules] โ†’ [Backtest] โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - -#### 2.2 Backtesting as a Service -```python -# API for custom backtesting -POST /api/backtest -{ - "strategy": "user_strategy_id", - "data_sources": ["kalshi", "custom_ws"], - "date_range": { - "start": "2024-01-01", - "end": "2024-12-31" - }, - "parameters": { - "stop_loss": 0.10, - "position_size": 0.05 - } -} - -# Response -{ - "sharpe_ratio": 2.87, - "total_return": 1.87, - "max_drawdown": -0.124, - "win_rate": 0.673, - "report_url": "https://platform.com/report/abc123" -} -``` - -#### 2.3 Strategy Marketplace -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ STRATEGY MARKETPLACE โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ Top Performers: โ”‚ -โ”‚ โ€ข MomentumPro โญ4.8 +187% return โ”‚ -โ”‚ โ€ข MeanReversion โญ4.6 +142% return โ”‚ -โ”‚ โ€ข EventArbitrage โญ4.5 +98% return โ”‚ -โ”‚ โ”‚ -โ”‚ [Deploy] [Clone] [Analyze] โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - -**Deliverables:** -- [ ] Web-based strategy builder -- [ ] REST API for backtesting -- [ ] Strategy marketplace MVP -- [ ] Performance analytics dashboard - ---- - -### Phase 3: Custom Data Integration (Q3 2025) -**Goal:** Support any data source and market - -#### 3.1 WebSocket Adapter Framework -```python -# Universal WebSocket adapter -class WebSocketAdapter: - def __init__(self, config): - self.url = config['url'] - self.auth = config['auth'] - self.parser = config['parser'] - - async def connect(self): - """Auto-configure from user spec""" - self.ws = await websockets.connect( - self.url, - extra_headers=self.auth - ) - - def parse_message(self, msg): - """User-defined parser or auto-detect""" - return self.parser(msg) -``` - -#### 3.2 Data Source Registry -```yaml -# User registers custom data source -data_sources: - - name: "crypto_exchange" - type: "websocket" - url: "wss://stream.exchange.com" - auth_type: "api_key" - message_format: "json" - mappings: - price: "$.last_price" - volume: "$.24h_volume" - - - name: "news_sentiment" - type: "rest_api" - url: "https://api.news.com/sentiment" - poll_interval: 60 - auth_type: "bearer_token" -``` - -#### 3.3 Multi-Exchange Support -```python -# Trade across multiple venues -class UniversalExecutor: - exchanges = { - 'kalshi': KalshiClient(), - 'polymarket': PolymarketClient(), - 'manifold': ManifoldClient(), - 'custom': UserExchangeClient() - } - - async def execute_best(self, order): - """Route to best execution venue""" - best_price = await self.find_best_price(order) - return await self.exchanges[best_price.venue].execute(order) -``` - -**Deliverables:** -- [ ] WebSocket adapter generator -- [ ] REST API adapter -- [ ] Database connectors (PostgreSQL, MongoDB) -- [ ] Multi-exchange execution router - ---- - -### Phase 4: Algorithm Marketplace (Q4 2025) -**Goal:** Create ecosystem for algorithm sharing and monetization - -#### 4.1 Algorithm Store -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ ALGORITHM STORE โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ Categories: โ”‚ -โ”‚ โ€ข Mean Reversion (45 algos) โ”‚ -โ”‚ โ€ข Momentum (82 algos) โ”‚ -โ”‚ โ€ข Arbitrage (31 algos) โ”‚ -โ”‚ โ€ข ML-Based (67 algos) โ”‚ -โ”‚ โ”‚ -โ”‚ Revenue Models: โ”‚ -โ”‚ โ€ข One-time purchase โ”‚ -โ”‚ โ€ข Subscription โ”‚ -โ”‚ โ€ข Profit sharing โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - -#### 4.2 Strategy Templates -```python -# Pre-built templates users can customize -templates = { - 'pairs_trading': PairsTradingTemplate(), - 'momentum': MomentumTemplate(), - 'mean_reversion': MeanReversionTemplate(), - 'ml_prediction': MLPredictionTemplate(), - 'event_driven': EventDrivenTemplate() -} - -# User customizes template -my_strategy = templates['momentum'].customize( - indicators=['RSI', 'MACD'], - entry_conditions={'RSI': '<30'}, - exit_conditions={'profit': '>5%'} -) -``` - -#### 4.3 Performance Verification -```python -# Verified performance tracking -class PerformanceVerifier: - """Cryptographically verify algorithm performance""" - - def verify_backtest(self, strategy_id): - """Independent backtest verification""" - return { - 'verified': True, - 'hash': 'abc123...', - 'performance': {...}, - 'certificate_url': '...' - } - - def track_live(self, strategy_id): - """Real-time performance tracking""" - return LivePerformanceTracker(strategy_id) -``` - -**Deliverables:** -- [ ] Algorithm marketplace platform -- [ ] Revenue sharing system -- [ ] Performance verification service -- [ ] Copy-trading functionality - ---- - -## ๐Ÿ› ๏ธ Technical Implementation - -### Core Architecture Extensions - -#### 1. Plugin System Architecture -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ PLUGIN MANAGER โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ โ”‚ -โ”‚ Plugin Types: โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ Data โ”‚ โ”‚ Strategy โ”‚ โ”‚ -โ”‚ โ”‚ Source โ”‚ โ”‚ Plugin โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ โ”‚ โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ Plugin Runtime โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Sandboxing โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข Resource limits โ”‚ โ”‚ -โ”‚ โ”‚ โ€ข API access control โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ”‚ โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - -#### 2. Custom Algorithm API -```python -# Base classes for user extensions -class CustomDataSource(ABC): - @abstractmethod - async def connect(self): pass - - @abstractmethod - async def subscribe(self, symbols): pass - - @abstractmethod - def transform(self, data): pass - -class CustomStrategy(ABC): - @abstractmethod - def analyze(self, data): pass - - @abstractmethod - def generate_signal(self, analysis): pass - - @abstractmethod - def calculate_position_size(self, signal): pass - -class CustomIndicator(ABC): - @abstractmethod - def calculate(self, data): pass - - @abstractmethod - def get_signal(self): pass -``` - -#### 3. Backtest Engine Extensions -```python -class UniversalBacktestEngine: - """Extended backtesting for any data/strategy""" - - def __init__(self): - self.data_sources = DataSourceRegistry() - self.strategies = StrategyRegistry() - self.validators = ValidationPipeline() - - async def backtest(self, config): - # Load custom data source - data = await self.data_sources.load( - config['data_source'], - config['date_range'] - ) - - # Load custom strategy - strategy = self.strategies.load( - config['strategy'], - config['parameters'] - ) - - # Run backtest with custom components - results = await self.run_simulation( - data, - strategy, - config['capital'] - ) - - return self.generate_report(results) -``` - -#### 4. SDK and CLI Tools -```bash -# Neural Trading Platform CLI -ntp create strategy momentum_breakout -ntp backtest --strategy momentum_breakout --data kalshi --from 2024-01-01 -ntp deploy momentum_breakout --capital 10000 --risk-limit 0.20 -ntp monitor momentum_breakout --dashboard - -# SDK usage -from ntp import Strategy, DataSource, Backtest - -class MyStrategy(Strategy): - def analyze(self, data): - # Custom logic - return signal - -# Register and backtest -strategy = MyStrategy() -backtest = Backtest(strategy, data_source="kalshi") -results = backtest.run(start="2024-01-01", end="2024-12-31") -``` - ---- - -## ๐Ÿ“ˆ Monetization Strategy - -### Revenue Streams - -#### 1. Platform Fees -- **Basic:** Free tier with limited backtests -- **Pro:** $99/month unlimited backtesting -- **Enterprise:** $999/month with priority execution - -#### 2. Marketplace Commission -- 30% commission on algorithm sales -- 20% on subscription revenues -- 15% on profit-sharing arrangements - -#### 3. Data Services -- Premium data feeds -- Historical data packages -- Real-time data API access - -#### 4. Managed Services -- White-label platform -- Custom strategy development -- Institutional deployment - ---- - -## ๐ŸŽฏ Success Metrics - -### Year 1 Goals -- 1,000+ registered developers -- 100+ custom strategies deployed -- 50+ data sources integrated -- $1M+ in platform transactions - -### Year 2 Goals -- 10,000+ active users -- 1,000+ algorithms in marketplace -- 500+ data sources -- $10M+ in platform transactions - -### Year 3 Goals -- 50,000+ users -- 5,000+ algorithms -- Institutional adoption -- $100M+ in platform transactions - ---- - -## ๐Ÿ”ง Implementation Timeline - -### Q1 2025: Foundation -- [ ] Week 1-4: Plugin architecture design -- [ ] Week 5-8: Strategy SDK development -- [ ] Week 9-12: Testing and documentation - -### Q2 2025: Developer Tools -- [ ] Week 1-4: Visual builder UI -- [ ] Week 5-8: Backtesting API -- [ ] Week 9-12: Marketplace MVP - -### Q3 2025: Data Integration -- [ ] Week 1-4: WebSocket framework -- [ ] Week 5-8: Multi-exchange support -- [ ] Week 9-12: Testing and optimization - -### Q4 2025: Marketplace Launch -- [ ] Week 1-4: Algorithm store -- [ ] Week 5-8: Performance verification -- [ ] Week 9-12: Marketing and launch - ---- - -## ๐Ÿš€ Quick Wins (Next 30 Days) - -### 1. Create Plugin Interface -```python -# Simple plugin interface to start -class PluginInterface: - def initialize(self, config): pass - def process(self, data): pass - def cleanup(self): pass -``` - -### 2. Add Custom Strategy Support -```python -# Allow users to drop in Python files -strategies/ - โ”œโ”€โ”€ user_strategy_1.py - โ”œโ”€โ”€ user_strategy_2.py - โ””โ”€โ”€ user_strategy_3.py -``` - -### 3. Extend Backtest Engine -```python -# Support custom data formats -backtest.add_data_source( - CSVDataSource("historical_data.csv") -) -``` - -### 4. Create Developer Docs -- Getting started guide -- API reference -- Example strategies -- Video tutorials - ---- - -## ๐ŸŽจ Platform Features Comparison - -| Feature | Current | Phase 1 | Phase 2 | Phase 3 | Phase 4 | -|---------|---------|---------|---------|---------|---------| -| Data Sources | Kalshi, ESPN, Twitter | +5 sources | +20 sources | Any WebSocket/API | Unlimited | -| Custom Strategies | No | Yes (code) | Yes (visual) | Templates | Marketplace | -| Backtesting | Built-in | API access | Cloud-based | Distributed | Verified | -| Markets | Kalshi only | 3 exchanges | 10 exchanges | Any exchange | Universal | -| Users | Single | Team | Organization | Public | Ecosystem | -| Revenue Model | Trading | SaaS | Platform fees | Marketplace | Full ecosystem | - ---- - -## ๐ŸŒŸ Competitive Advantages - -### Why This Platform Will Win - -1. **Open Architecture** - - Unlike QuantConnect: Not locked to specific brokers - - Unlike TradingView: Full algorithmic capabilities - - Unlike MT4/MT5: Modern tech stack and AI - -2. **Network Effects** - - More strategies โ†’ More users - - More users โ†’ More data sources - - More data โ†’ Better strategies - -3. **Developer-First** - - Excellent documentation - - Simple SDK - - Active community - - Revenue sharing - -4. **Technology Edge** - - Sub-100ms latency - - Distributed backtesting - - AI/ML integration - - Cloud-native architecture - ---- - -## ๐Ÿ“ž Next Steps - -### Immediate Actions -1. **Technical Design**: Finalize plugin architecture -2. **Community Building**: Launch developer forum -3. **Partnerships**: Connect with data providers -4. **Funding**: Raise Series A for platform development - -### Contact for Collaboration -- **Developers**: Join our beta program -- **Data Providers**: Partner with us -- **Investors**: Fund the future of algo trading -- **Traders**: Test early access features - ---- - -*The Neural Trading Platform will democratize algorithmic trading by providing institutional-grade infrastructure to every developer and trader.* \ No newline at end of file diff --git a/README.md b/README.md index b2362cda..17a2c1c2 100644 --- a/README.md +++ b/README.md @@ -1,332 +1,249 @@ -# ๐Ÿˆ Neural Trading Platform - Autonomous Sports Event Trading +# ๐Ÿง  Neural SDK -> **Real-time algorithmic trading system for Kalshi sports prediction markets** -> Monitors multiple data sources โ€ข Detects market inefficiencies โ€ข Executes trades in <3 seconds +> **Open-source Python SDK for algorithmic prediction market trading** +> Build sophisticated trading strategies with real-time data streaming and comprehensive backtesting - -## ๐ŸŽฏ What This Does - -This platform automatically trades sports prediction markets on Kalshi by detecting and exploiting information asymmetries faster than human traders. - -### Real Example -``` -18:35:22 - ESPN: "Touchdown Chiefs! Mahomes 45-yard pass" -18:35:22 - Platform detects event (100ms) -18:35:22 - Checks Kalshi price: still at 0.65 (hasn't moved) -18:35:23 - Places BUY order: 1,923 shares @ 0.65 -18:35:24 - Order filled -18:35:37 - Kalshi price moves to 0.70 -18:35:37 - Profit: +7.7% in 15 seconds -``` +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) +[![PyPI version](https://badge.fury.io/py/neural-sdk.svg)](https://badge.fury.io/py/neural-sdk) ## ๐Ÿš€ Quick Start -### Prerequisites -- Python 3.10+ -- Redis server -- Kalshi account (for live trading) -- Free API keys for data sources +### Installation -### 1. Clone & Setup ```bash -git clone https://github.com/IntelIP/Neural-Trading-Platform.git -cd Neural-Trading-Platform -pip install -r requirements.txt -``` +pip install neural-sdk -### 2. Configure APIs -Create `.env` file: -```bash -# Trading (required for live trading) -KALSHI_API_KEY_ID=your_key_id -KALSHI_API_KEY=your_api_key - -# Data Sources (weather API included free) -OPENWEATHER_API_KEY=78596505b0f5fea89e98ebcbf3bd6e21 # Working key -REDDIT_CLIENT_ID=your_reddit_id # Optional -REDDIT_CLIENT_SECRET=your_reddit_secret # Optional +# Or install from GitHub +pip install git+https://github.com/IntelIP/kalshi.git@feat/synthetic-training-integration ``` -### 3. Start Redis -```bash -# macOS -brew install redis && brew services start redis +### Basic Usage -# Linux -sudo apt-get install redis-server && sudo systemctl start redis +```python +from neural_sdk import NeuralSDK -# Verify -redis-cli ping # Should return PONG -``` +# Initialize SDK +sdk = NeuralSDK.from_env() -### 4. Test the System -```bash -# Test weather monitoring (working API included) -python scripts/quick_weather_demo.py +# Create a simple strategy +@sdk.strategy +async def momentum_strategy(market_data): + for symbol, price in market_data.prices.items(): + if 'NFL' in symbol and price < 0.3: + return sdk.create_signal('BUY', symbol, size=100) -# Full SDK demo -python scripts/demo_sdk.py +# Start trading +await sdk.start_trading() +``` -# Paper trading mode -python scripts/run_agents.py --paper-trading +### Backtesting + +```python +from neural_sdk.backtesting import BacktestEngine, BacktestConfig + +# Configure backtest +config = BacktestConfig( + start_date="2024-01-01", + end_date="2024-12-31", + initial_capital=10000 +) + +# Run backtest +engine = BacktestEngine(config) +engine.add_strategy(my_strategy) +engine.load_data("csv", path="historical_data.csv") + +results = engine.run() +print(f"Total Return: {results.total_return:.2f}%") +print(f"Sharpe Ratio: {results.metrics['sharpe_ratio']:.3f}") ``` -## ๐Ÿ—๏ธ How It Works +## ๐Ÿ—๏ธ Architecture ```mermaid graph LR A[Data Sources] --> B[SDK Adapters] - B --> C[Redis Pub/Sub] - C --> D[Trading Agents] - D --> E[Kalshi API] + B --> C[Strategy Engine] + C --> D[Kalshi API] - A1[DraftKings
Odds] --> B - A2[Weather
Conditions] --> B - A3[Reddit
Sentiment] --> B - A4[ESPN
GameCast] --> B + A1[Weather API] --> B + A2[Reddit Sentiment] --> B + A3[Sports APIs] --> B - D1[DataCoordinator] --> D - D2[StrategyAnalyst] --> D - D3[TradeExecutor] --> D - D4[RiskManager] --> D + E[Backtesting Engine] --> F[Performance Analytics] ``` -### Data Flow Timeline -| Step | Component | Latency | Action | -|------|-----------|---------|--------| -| 1 | ESPN GameCast | 0ms | "Touchdown!" event detected | -| 2 | SDK Adapter | +100ms | Converts to StandardizedEvent | -| 3 | Redis Pub/Sub | +10ms | Distributes to subscribers | -| 4 | DataCoordinator | +200ms | Correlates with Kalshi price | -| 5 | StrategyAnalyst | +300ms | Calculates expected move | -| 6 | TradeExecutor | +200ms | Places order via API | -| **Total** | **End-to-end** | **810ms** | **Sub-second execution** | +## ๐Ÿ“Š Features -## ๐Ÿ“Š Data Source SDK +### Core Trading +- **Real-time market data** streaming from multiple sources +- **Strategy framework** with easy-to-use decorators +- **Risk management** with position limits and stop-losses +- **Order execution** with realistic slippage simulation -The platform's edge comes from its modular Data Source SDK that makes adding new data sources trivial: +### Backtesting +- **Event-driven engine** for accurate historical testing +- **Multiple data sources**: CSV, Parquet, SQL, S3 +- **Performance metrics**: Sharpe ratio, drawdown, win rate +- **Portfolio simulation** with realistic costs and slippage -### Currently Implemented +### Data Integration +- **Plugin architecture** for custom data sources +- **Built-in adapters** for weather, Reddit, sports APIs +- **Data caching** for improved performance +- **Format standardization** across all sources -| Source | Status | Latency | Purpose | API Required | -|--------|--------|---------|---------|--------------| -| **Weather** | โœ… Working | 2s | Wind/rain affects scoring | Included (free) | -| **DraftKings** | โœ… Ready | 500ms | Sharp money movements | None (public) | -| **Reddit** | โš™๏ธ Configured | 2-5s | Sentiment extremes | Yes (free) | -| **ESPN** | ๐Ÿ”„ Planned | 1-2s | Official game events | Development | +## ๐Ÿ› ๏ธ Data Sources -### Add Your Own Source (50 lines) -```python -from src.sdk import DataSourceAdapter, StandardizedEvent, EventType +| Source | Status | Purpose | Setup | +|--------|--------|---------|-------| +| **Weather API** | โœ… Ready | Weather impacts on sports | Free API key | +| **Reddit** | โœ… Ready | Sentiment analysis | Free API credentials | +| **Custom CSV** | โœ… Ready | Historical data | Local files | +| **Parquet** | โœ… Ready | High-performance data | S3 or local | +| **PostgreSQL** | โš™๏ธ Optional | Large datasets | Database connection | -class MyAdapter(DataSourceAdapter): - async def connect(self): - self.client = YourAPIClient(self.config['api_key']) - return await self.client.connect() - - async def stream(self): - while self.is_connected: - data = await self.fetch_data() - - # Detect trading opportunity - if self.is_significant(data): - yield StandardizedEvent( - source="MySource", - event_type=EventType.CUSTOM, - data=data, - confidence=0.85, - impact="high" - ) - - await asyncio.sleep(self.config['interval']) +## ๐Ÿ“ˆ Strategy Examples + +### Momentum Strategy +```python +def momentum_strategy(market_data): + \"\"\"Buy markets trending upward below 60 cents\"\"\" + for symbol, price in market_data.prices.items(): + if price < 0.6 and market_data.is_trending_up(symbol): + return {'action': 'BUY', 'symbol': symbol, 'size': 50} ``` -## ๐Ÿค– Trading Intelligence +### Mean Reversion +```python +def mean_reversion_strategy(market_data): + \"\"\"Buy undervalued markets, sell overvalued\"\"\" + for symbol, price in market_data.prices.items(): + if price < 0.3: # Undervalued + return {'action': 'BUY', 'symbol': symbol, 'size': 100} + elif price > 0.7: # Overvalued + return {'action': 'SELL', 'symbol': symbol, 'size': 100} +``` -### Signal Generation -The platform correlates events across sources to identify opportunities: +## ๐Ÿ”ง Configuration -```python -# Example: Weather + Odds Correlation -if weather.wind_speed > 20 and not draftkings.total_moved: - signal = Signal( - action="BET_UNDER", - confidence=0.75, - edge=0.04, # 4% expected value - reason="High wind not priced into total" - ) +### Environment Setup +```bash +# Create .env file +NEURAL_API_KEY_ID=your_neural_api_key +NEURAL_PRIVATE_KEY_FILE=./keys/neural_private.key + +# Optional: Data source APIs +OPENWEATHER_API_KEY=your_weather_key +REDDIT_CLIENT_ID=your_reddit_id +REDDIT_CLIENT_SECRET=your_reddit_secret ``` -### Position Sizing (Kelly Criterion) +### SDK Configuration ```python -# Never use full Kelly - too risky -position = kelly_fraction * 0.25 # 25% of Kelly -position = min(position, 0.05 * capital) # Max 5% per trade +from neural_sdk import SDKConfig + +config = SDKConfig( + max_position_size=0.05, # Max 5% per position + daily_loss_limit=0.20, # Stop at 20% daily loss + commission=0.02, # Kalshi's 2% fee + slippage=0.01 # 1% estimated slippage +) + +sdk = KalshiSDK(config) ``` -### Risk Management -- **Stop Loss**: -5% automatic exit -- **Daily Limit**: -20% circuit breaker -- **Correlation Check**: Reduce correlated positions -- **Max Positions**: 10 concurrent trades +## ๐Ÿ“š Documentation -## ๐Ÿ“ˆ Performance Metrics +| Document | Description | +|----------|-------------| +| [**Getting Started**](docs/getting_started.md) | Installation and first strategy | +| [**API Reference**](docs/api_reference.md) | Complete SDK documentation | +| [**Backtesting Guide**](docs/backtesting.md) | Historical testing framework | +| [**Data Sources**](docs/data_sources.md) | Setting up data feeds | +| [**Strategy Development**](docs/strategies.md) | Building trading algorithms | -### Backtested Results (30 days) -| Metric | Value | Target | -|--------|-------|--------| -| **Win Rate** | 67.3% | >65% | -| **Sharpe Ratio** | 2.14 | >2.0 | -| **Avg Return/Trade** | +1.8% | >1.5% | -| **Max Drawdown** | -18.2% | <20% | -| **Trades/Day** | 12 | 10-20 | +## ๐Ÿงช Testing -### Live Performance Tracking ```bash -# Monitor real-time performance -python scripts/monitor_performance.py +# Run all tests +pytest tests/ -# Run backtest on strategy -python scripts/run_backtest.py --strategy sharp_money --days 30 -``` +# Run specific test suite +pytest tests/unit/test_backtesting.py -## ๐ŸŽฎ Configuration Examples - -### Monitor Specific Game -```yaml -# config/game_config.yaml -game_monitoring: - mode: "single_game" - game: - sport: "NFL" - home_team: "Kansas City Chiefs" - away_team: "Buffalo Bills" - - kalshi_markets: - - "NFL-KC-BUF-WINNER" - - "NFL-KC-BUF-TOTAL" +# Run with coverage +pytest --cov=kalshi_trading_sdk tests/ ``` -### Weather Impact Settings -```yaml -# config/data_sources.yaml -weather: - enabled: true - thresholds: - wind_speed: 15 # mph - affects passing - precipitation: 0.1 # in/hr - affects scoring -``` +## ๐Ÿ“Š Performance Metrics -## ๐Ÿงช Testing +The SDK calculates comprehensive metrics for strategy evaluation: -```bash -# Unit tests -pytest tests/unit/ +- **Return Metrics**: Total return, CAGR, Sharpe ratio +- **Risk Metrics**: Max drawdown, volatility, VaR +- **Trade Analysis**: Win rate, average win/loss, profit factor +- **Time Analysis**: Best/worst days, consecutive wins/losses -# Integration tests -pytest tests/integration/ +## ๐ŸŒŸ Example Results -# Test specific adapter -python scripts/test_weather_adapter.py - -# Load testing -python tests/load/stress_test.py +``` +BACKTEST RESULTS +================ +Period: 2024-01-01 to 2024-12-31 +Initial Capital: $10,000.00 +Final Value: $12,750.00 + +Total Return: +27.5% +Sharpe Ratio: 1.85 +Max Drawdown: -8.2% +Win Rate: 68.5% +Total Trades: 156 ``` -## ๐Ÿ“š Documentation +## ๐Ÿค Contributing -| Document | Description | -|----------|-------------| -| [Getting Started](docs/GETTING_STARTED.md) | Installation and first trade | -| [System Overview](docs/SYSTEM_OVERVIEW.md) | Architecture deep dive | -| [SDK Documentation](docs/SDK_DOCUMENTATION.md) | Build custom adapters | -| [Trading Logic](docs/TRADING_LOGIC.md) | How decisions are made | -| [Data Sources Guide](docs/DATA_SOURCES_GUIDE.md) | Configure each source | - -## ๐Ÿšฆ Project Status - -### โœ… Completed -- Data Source SDK framework -- Weather monitoring (OpenWeatherMap API) -- DraftKings odds adapter -- Reddit sentiment adapter -- Redis pub/sub message bus -- Kelly Criterion position sizing -- Risk management system -- Comprehensive documentation - -### ๐Ÿ”„ In Development -- ESPN GameCast integration -- Machine learning signal enhancement -- Multi-sport expansion (NBA, MLB) - -### ๐Ÿ“… Roadmap -- Q4 2024: Production deployment -- Q1 2025: ML model integration -- Q2 2025: Mobile monitoring app - -## ๐Ÿ› ๏ธ Tech Stack - -- **Python 3.10+** - Async/await for speed -- **Redis** - 10,000 msg/sec pub/sub -- **Agentuity** - Agent orchestration -- **aiohttp** - Async HTTP client -- **asyncpraw** - Reddit streaming -- **pandas/numpy** - Data analysis -- **TextBlob** - Sentiment analysis - -## ๐Ÿ“Š System Requirements - -### Minimum (Development) -- 2 CPU cores -- 4 GB RAM -- 10 GB storage -- 10 Mbps internet - -### Recommended (Production) -- 4+ CPU cores -- 8 GB RAM -- 50 GB SSD -- 100 Mbps internet -- Redis dedicated instance +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. -## ๐Ÿค Contributing +### Development Setup +```bash +git clone https://github.com/neural/neural-sdk.git +cd neural-sdk -We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +# Install development dependencies +pip install -e ".[dev]" -### Areas Needing Help -- ESPN WebSocket integration -- Additional sports adapters -- ML model development -- Performance optimization +# Run pre-commit hooks +pre-commit install +``` -## ๐Ÿ“ License +## ๐Ÿ“„ License -MIT License - see [LICENSE](LICENSE) file +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## โš ๏ธ Disclaimer -**IMPORTANT**: This software is for educational purposes. Sports event trading involves significant risk of loss. +**Important**: This software is for educational and research purposes. Trading involves substantial risk of loss. - Always start with paper trading -- Never risk more than you can afford to lose +- Never risk more than you can afford to lose - Past performance doesn't guarantee future results -- The platform is not financial advice +- The SDK is not financial advice -## ๐Ÿ† Acknowledgments +## ๐Ÿ”— Links -- Kalshi for providing the trading platform -- OpenWeatherMap for weather data (API key included) -- Reddit community for sentiment data -- DraftKings for odds reference data +- **Documentation**: [https://kalshi-trading-sdk.readthedocs.io/](https://kalshi-trading-sdk.readthedocs.io/) +- **PyPI Package**: [https://pypi.org/project/kalshi-trading-sdk/](https://pypi.org/project/kalshi-trading-sdk/) +- **Issues**: [https://github.com/kalshi/kalshi-trading-sdk/issues](https://github.com/kalshi/kalshi-trading-sdk/issues) +- **Discussions**: [https://github.com/kalshi/kalshi-trading-sdk/discussions](https://github.com/kalshi/kalshi-trading-sdk/discussions) -## ๐Ÿ“ž Support +## ๐Ÿ† Acknowledgments -- ๐Ÿ“– [Documentation](docs/) -- ๐Ÿ’ฌ [GitHub Issues](https://github.com/IntelIP/Neural-Trading-Platform/issues) -- ๐Ÿ“ง Contact: [your-email] +- Kalshi for providing the trading platform +- Contributors and beta testers +- Open source community for excellent libraries --- -**Built for algorithmic trading** -*Trade responsibly. Speed matters. Edge wins.* \ No newline at end of file +**Built for algorithmic trading โ€ข Trade responsibly โ€ข Performance matters** \ No newline at end of file diff --git a/config/data_sources.yaml b/config/data_sources.yaml index 04f8a009..1dd43fcd 100644 --- a/config/data_sources.yaml +++ b/config/data_sources.yaml @@ -6,7 +6,7 @@ sources: - name: draftkings enabled: true class: DraftKingsAdapter - module: src.sdk.adapters.draftkings + module: sdk.adapters.draftkings priority: 1 # Higher priority = processed first config: sports: @@ -20,7 +20,7 @@ sources: - name: reddit enabled: false # Enable after adding credentials class: RedditAdapter - module: src.sdk.adapters.reddit + module: sdk.adapters.reddit priority: 2 config: client_id: ${REDDIT_CLIENT_ID} @@ -37,14 +37,30 @@ sources: injury: ["injury", "injured", "hurt", "down"] big_play: ["holy shit", "wow", "incredible"] + # ESPN Play-by-Play Data + - name: espn + enabled: true # No API key needed - completely free! + class: ESPNAdapter + module: sdk.adapters.espn + priority: 1 # High priority for real-time game events + config: + sports: + - nfl + - nba + update_interval: 5 # Base polling interval in seconds + critical_interval: 3 # Interval during critical game moments + # Optional: Monitor specific games by ID + # games: + # - "401547652" + # Weather Conditions - name: weather enabled: true # API key is working! class: WeatherAdapter - module: src.sdk.adapters.weather + module: sdk.adapters.weather priority: 3 config: - api_key: 78596505b0f5fea89e98ebcbf3bd6e21 # Your working API key + api_key: ${OPENWEATHER_API_KEY} update_interval: 300 # 5 minutes thresholds: wind_speed: 15 # mph @@ -73,4 +89,4 @@ settings: event_queue_size: 10000 max_adapters: 10 health_check_interval: 60 # seconds - log_level: INFO \ No newline at end of file + log_level: INFO diff --git a/config/environments/development.yaml b/config/environments/development.yaml new file mode 100644 index 00000000..ed2d5640 --- /dev/null +++ b/config/environments/development.yaml @@ -0,0 +1,87 @@ +# Development Environment Configuration +# For local development and testing + +name: "Development" +environment: "development" +redis_db: 4 +redis_prefix: "dev:" + +api_endpoints: + kalshi: "http://localhost:8000/mock/kalshi" + odds: "http://localhost:8001/mock/odds" + sportsdata: "http://localhost:8002/mock/sportsdata" + twitter: "http://localhost:8003/mock/twitter" + +rate_limits: + kalshi: 100000 + odds: 100000 + sportsdata: 100000 + twitter: 100000 + +# Safety and Security +safety_checks: false +require_confirmation: false +require_mfa: false + +# Allowed Operations +allowed_operations: + - "*" # All operations allowed in development + +# Restricted Operations +restricted_operations: [] # No restrictions in development + +# Data Management +data_retention_hours: 1 # Minimal retention +backup_enabled: false +backup_frequency_hours: 0 + +# Trading Limits (No limits for development) +max_position_size: 1.0 +max_daily_trades: 100000 +max_concurrent_positions: 10000 +max_order_value: 10000000.0 +min_order_value: 0.001 + +# Risk Management (Disabled for development) +stop_loss_percentage: 1.0 +max_drawdown_percentage: 1.0 +position_sizing_method: "fixed" +kelly_fraction: 1.0 + +# Logging and Monitoring +enable_logging: true +log_level: "DEBUG" +telemetry_enabled: false +alert_enabled: false +alert_channels: [] + +# Feature Flags +features: + auto_trading: true + paper_trading: true + backtesting: true + synthetic_data: true + debug_mode: true + performance_profiling: true + real_time_analytics: false + emergency_stop: false + development_mode: true + hot_reload: true + mock_apis: true + verbose_logging: true + +# Development Specific Settings +development: + auto_reload: true + debug_toolbar: true + sql_echo: true + mock_delay_ms: 0 + bypass_cache: true + show_stack_traces: true + +# Monitoring Thresholds (Disabled for development) +monitoring: + latency_threshold_ms: 10000 + error_rate_threshold: 1.0 + memory_threshold_gb: 16 + cpu_threshold_percent: 100 \ No newline at end of file diff --git a/config/environments/production.yaml b/config/environments/production.yaml new file mode 100644 index 00000000..d2d9bf97 --- /dev/null +++ b/config/environments/production.yaml @@ -0,0 +1,86 @@ +# Production Environment Configuration +# CRITICAL: This configuration is for LIVE TRADING with REAL MONEY + +name: "Production" +environment: "production" +redis_db: 0 +redis_prefix: "prod:" + +api_endpoints: + kalshi: "https://api.kalshi.com" + odds: "https://api.theoddsapi.com/v4" + sportsdata: "https://api.sportsdata.io/v3/nfl" + twitter: "https://api.twitter.com/2" + +rate_limits: + kalshi: 100 + odds: 50 + sportsdata: 100 + twitter: 300 + +# Safety and Security +safety_checks: true +require_confirmation: true +require_mfa: true + +# Allowed Operations +allowed_operations: + - "place_order" + - "cancel_order" + - "get_positions" + - "get_markets" + - "get_account" + - "analyze_market" + - "calculate_kelly" + +# Restricted Operations +restricted_operations: + - "delete_all_data" + - "reset_account" + - "modify_system_config" + - "bypass_risk_checks" + +# Data Management +data_retention_hours: 720 # 30 days +backup_enabled: true +backup_frequency_hours: 24 + +# Trading Limits +max_position_size: 0.05 # 5% of portfolio +max_daily_trades: 20 +max_concurrent_positions: 10 +max_order_value: 1000.0 +min_order_value: 1.0 + +# Risk Management +stop_loss_percentage: 0.10 +max_drawdown_percentage: 0.20 +position_sizing_method: "kelly_fraction" +kelly_fraction: 0.25 + +# Logging and Monitoring +enable_logging: true +log_level: "INFO" +telemetry_enabled: true +alert_enabled: true +alert_channels: + - "email" + - "slack" + +# Feature Flags +features: + auto_trading: true + paper_trading: false + backtesting: false + synthetic_data: false + debug_mode: false + performance_profiling: true + real_time_analytics: true + emergency_stop: true + +# Monitoring Thresholds +monitoring: + latency_threshold_ms: 1000 + error_rate_threshold: 0.01 + memory_threshold_gb: 4 + cpu_threshold_percent: 80 \ No newline at end of file diff --git a/config/environments/sandbox.yaml b/config/environments/sandbox.yaml new file mode 100644 index 00000000..9f44e836 --- /dev/null +++ b/config/environments/sandbox.yaml @@ -0,0 +1,86 @@ +# Sandbox Environment Configuration +# For testing with demo APIs and safe experimentation + +name: "Sandbox" +environment: "sandbox" +redis_db: 2 +redis_prefix: "sandbox:" + +api_endpoints: + kalshi: "https://demo-api.kalshi.co" + odds: "https://api.theoddsapi.com/v4" + sportsdata: "https://api.sportsdata.io/v3/nfl" + twitter: "https://api.twitter.com/2" + +rate_limits: + kalshi: 500 + odds: 200 + sportsdata: 200 + twitter: 500 + +# Safety and Security +safety_checks: true +require_confirmation: false +require_mfa: false + +# Allowed Operations +allowed_operations: + - "*" # All operations allowed in sandbox + +# Restricted Operations +restricted_operations: + - "delete_production_data" + - "modify_production_config" + +# Data Management +data_retention_hours: 24 # 1 day retention +backup_enabled: false +backup_frequency_hours: 0 + +# Trading Limits (Moderate for sandbox) +max_position_size: 0.20 # 20% of portfolio +max_daily_trades: 100 +max_concurrent_positions: 50 +max_order_value: 10000.0 +min_order_value: 0.10 + +# Risk Management +stop_loss_percentage: 0.20 +max_drawdown_percentage: 0.40 +position_sizing_method: "kelly_fraction" +kelly_fraction: 0.50 + +# Logging and Monitoring +enable_logging: true +log_level: "DEBUG" +telemetry_enabled: false +alert_enabled: false +alert_channels: [] + +# Feature Flags +features: + auto_trading: true + paper_trading: true + backtesting: true + synthetic_data: false + debug_mode: true + performance_profiling: true + real_time_analytics: true + emergency_stop: true + sandbox_mode: true + api_mocking: true + +# Sandbox Specific Settings +sandbox: + reset_daily: true + demo_balance: 10000.0 + unlimited_retries: true + skip_authentication: false + mock_latency_ms: 100 + +# Monitoring Thresholds +monitoring: + latency_threshold_ms: 2000 + error_rate_threshold: 0.05 + memory_threshold_gb: 4 + cpu_threshold_percent: 90 \ No newline at end of file diff --git a/config/environments/training.yaml b/config/environments/training.yaml new file mode 100644 index 00000000..8842409b --- /dev/null +++ b/config/environments/training.yaml @@ -0,0 +1,96 @@ +# Training Environment Configuration +# For agent training with synthetic data + +name: "Training" +environment: "training" +redis_db: 3 +redis_prefix: "training:" + +api_endpoints: + kalshi: "http://localhost:8000/mock/kalshi" + odds: "http://localhost:8001/mock/odds" + sportsdata: "http://localhost:8002/mock/sportsdata" + twitter: "http://localhost:8003/mock/twitter" + +rate_limits: + kalshi: 10000 + odds: 10000 + sportsdata: 10000 + twitter: 10000 + +# Safety and Security +safety_checks: false +require_confirmation: false +require_mfa: false + +# Allowed Operations +allowed_operations: + - "*" # All operations allowed in training + +# Restricted Operations +restricted_operations: [] # No restrictions in training + +# Data Management +data_retention_hours: 4 # Short retention for training data +backup_enabled: false +backup_frequency_hours: 0 + +# Trading Limits (Relaxed for training) +max_position_size: 1.0 # 100% allowed for training +max_daily_trades: 10000 +max_concurrent_positions: 1000 +max_order_value: 1000000.0 +min_order_value: 0.01 + +# Risk Management (Configurable for training) +stop_loss_percentage: 0.50 +max_drawdown_percentage: 1.0 +position_sizing_method: "kelly_fraction" +kelly_fraction: 1.0 # Full Kelly for training experiments + +# Logging and Monitoring +enable_logging: true +log_level: "DEBUG" +telemetry_enabled: false +alert_enabled: false +alert_channels: [] + +# Feature Flags +features: + auto_trading: true + paper_trading: true + backtesting: true + synthetic_data: true + debug_mode: true + performance_profiling: true + real_time_analytics: false + emergency_stop: false + training_mode: true + exploration_mode: true + replay_mode: true + +# Training Specific Settings +training: + scenario_generation: true + adaptive_difficulty: true + performance_tracking: true + decision_replay: true + confidence_calibration: true + memory_system: true + batch_size: 32 + learning_rate: 0.001 + +# Synthetic Data Settings +synthetic_data: + generation_enabled: true + realistic_timing: true + market_reaction_simulation: true + price_impact_modeling: true + volatility_injection: true + +# Monitoring Thresholds (Relaxed for training) +monitoring: + latency_threshold_ms: 5000 + error_rate_threshold: 0.10 + memory_threshold_gb: 8 + cpu_threshold_percent: 95 \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..3a63b70b --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,23 @@ +version: "3.9" + +services: + redis: + image: redis:7-alpine + container_name: neural_redis + ports: + - "6379:6379" + volumes: + - redis_data:/data + command: ["redis-server", "--appendonly", "yes"] + + app: + build: . + depends_on: + - redis + env_file: + - .env + command: ["python", "-c", "import neural_sdk; print('Neural SDK ready with env')"] + +volumes: + redis_data: + diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6d8a9e10..5ad19a7a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,7 +1,7 @@ -# Kalshi Trading Agent Architecture +# Neural Trading Agent Architecture ## Overview -A practical multi-agent system for automated sports betting on Kalshi, with clear separation between always-on monitoring agents and on-demand analysis agents. +A practical multi-agent system for automated sports betting on Neural, with clear separation between always-on monitoring agents and on-demand analysis agents. ## Agent Types @@ -13,7 +13,7 @@ A practical multi-agent system for automated sports betting on Kalshi, with clea **Responsibilities:** - Monitor ESPN for live games and scores - Track Twitter sentiment in real-time -- Watch Kalshi market prices and volumes +- Watch Neural market prices and volumes - Store historical data for analysis - Detect anomalies and significant events @@ -36,8 +36,8 @@ class DataCollectionAgent: # Monitor Twitter sentiment = await self.consume_twitter_stream() - # Monitor Kalshi - markets = await self.consume_kalshi_stream() + # Monitor Neural + markets = await self.consume_neural_stream() # Detect triggers if self.detect_opportunity(espn_data, sentiment, markets): @@ -110,7 +110,7 @@ class GameAnalystAgent: injuries = await self.get_injury_report(teams) # 3. Market Analysis - market_data = await self.get_kalshi_markets(game_id) + market_data = await self.get_neural_markets(game_id) implied_prob = self.calculate_implied_probability(market_data) # 4. Sentiment Analysis @@ -408,7 +408,7 @@ data_collector: enabled: true mode: always_on redis_channels: - - kalshi:markets + - neural:markets - espn:games - twitter:sentiment diff --git a/docs/DATA_SOURCES_GUIDE.md b/docs/DATA_SOURCES_GUIDE.md index f7368261..9fe679ce 100644 --- a/docs/DATA_SOURCES_GUIDE.md +++ b/docs/DATA_SOURCES_GUIDE.md @@ -10,7 +10,7 @@ Each data source provides unique alpha for trading decisions. This guide explain ### 1. DraftKings Sportsbook -**Purpose**: Professional odds movements often lead Kalshi markets by 5-30 seconds +**Purpose**: Professional odds movements often lead Neural markets by 5-30 seconds **What It Provides**: - Real-time odds for all major sports diff --git a/docs/GAME_CONFIGURATION_GUIDE.md b/docs/GAME_CONFIGURATION_GUIDE.md index 3a59c81c..05c5a5f2 100644 --- a/docs/GAME_CONFIGURATION_GUIDE.md +++ b/docs/GAME_CONFIGURATION_GUIDE.md @@ -24,8 +24,8 @@ game_monitoring: start_time: "2024-01-21T18:30:00Z" venue: "Arrowhead Stadium" - # Kalshi markets to trade - kalshi_markets: + # Neural markets to trade + neural_markets: - "NFL-KC-BUF-WINNER" - "NFL-KC-BUF-SPREAD" - "NFL-KC-BUF-TOTAL" @@ -213,7 +213,7 @@ auto_discovery: # Find games with these criteria criteria: - min_kalshi_volume: 10000 # Minimum liquidity + min_neural_volume: 10000 # Minimum liquidity min_edge_required: 0.03 # 3% edge sports: ["NFL", "NBA"] @@ -586,7 +586,7 @@ def validate_game_config(config): errors = [] # Check required fields - required = ['game_monitoring', 'kalshi_markets', 'data_sources'] + required = ['game_monitoring', 'neural_markets', 'data_sources'] for field in required: if field not in config: errors.append(f"Missing required field: {field}") diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index c7a20cce..f1316416 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -1,418 +1,25 @@ -# Getting Started - Neural Trading Platform +# Getting Started with Neural SDK -## Prerequisites - -Before you begin, ensure you have: - -- Python 3.10 or higher -- Redis server installed -- Git for version control -- At least one API key (Kalshi, DraftKings, Reddit, or OpenWeatherMap) - ---- +Welcome to the Neural SDK! This guide will help you get up and running with your first trading strategy. ## Installation -### 1. Clone the Repository - -```bash -git clone https://github.com/IntelIP/Neural-Trading-Platform.git -cd Neural-Trading-Platform -``` - -### 2. Install Dependencies - -```bash -# Using pip -pip install -r requirements.txt - -# Or using uv (recommended for faster installs) -uv pip install -r requirements.txt -``` - -### 3. Set Up Redis - -```bash -# macOS -brew install redis -brew services start redis - -# Ubuntu/Debian -sudo apt-get install redis-server -sudo systemctl start redis - -# Verify Redis is running -redis-cli ping -# Should return: PONG -``` - -### 4. Configure Environment Variables - -Create a `.env` file in the project root: - -```bash -# Kalshi Trading (Required) -KALSHI_API_KEY_ID=your_key_id_here -KALSHI_API_KEY=your_api_key_here - -# Data Sources (Optional - add what you have) -REDDIT_CLIENT_ID=your_reddit_client_id -REDDIT_CLIENT_SECRET=your_reddit_secret -OPENWEATHER_API_KEY=your_weather_api_key -``` - ---- - -## Quick Start: Monitor Your First Game - -### Step 1: Configure a Game to Monitor - -Edit `config/data_sources.yaml` to enable your available data sources: - -```yaml -sources: - # If you have a weather API key, enable this - - name: weather - enabled: true # Change from false to true - config: - api_key: ${OPENWEATHER_API_KEY} - - # DraftKings is free, enable this - - name: draftkings - enabled: true - config: - sports: - - NFL # Pick the sport you want -``` - -### Step 2: Run the SDK Demo - -This will show you data flowing through the system: - -```bash -python scripts/demo_sdk.py -``` - -You'll see output like: -``` -๐Ÿ“ก Initializing data sources... -โœ… Loaded 2 adapters: - โ€ข DraftKings v1.0.0 - Type: sportsbook - Latency: 500ms - Reliability: 95.0% - โ€ข Weather v1.0.0 - Type: environmental - Latency: 2000ms - Reliability: 99.0% - -๐Ÿš€ Starting data streams... -๐Ÿ“Š Processing events (30 seconds)... - -๐Ÿ“Š Odds Change: Chiefs vs Bills - Market: spread - Change: 0.650 โ†’ 0.675 - Direction: up - -๐ŸŒค๏ธ Weather Alert: Arrowhead Stadium - Condition: high_wind - Impact: ['passing_game', 'field_goals', 'punts'] -``` - -### Step 3: Connect to Kalshi Markets - -Once you have Kalshi API credentials, start the full platform: - -```bash -# Start the unified stream manager -python -m src.data_pipeline.orchestration.unified_stream_manager - -# In another terminal, start agent consumers -python examples/agent_redis_consumer.py all -``` - ---- - -## Understanding the Data Flow - -Here's what happens when you run the platform: - -``` -1. Data Sources Connect - โ†“ -2. Events Stream In (odds changes, weather updates, etc.) - โ†“ -3. Stream Manager Standardizes Events - โ†“ -4. Redis Distributes to Subscribers - โ†“ -5. Agents Analyze for Opportunities - โ†“ -6. Trading Signals Generated - โ†“ -7. Orders Placed on Kalshi -``` - -### Real Example: Touchdown Scored - -``` -ESPN GameCast โ†’ "Touchdown Chiefs!" - โ†“ (100ms) -Stream Manager โ†’ StandardizedEvent(type=GAME_EVENT, impact=HIGH) - โ†“ (10ms) -Redis Pub/Sub โ†’ Channel: "espn:games" - โ†“ (5ms) -DataCoordinator โ†’ Detects Kalshi price hasn't moved - โ†“ (200ms) -StrategyAnalyst โ†’ Calculates expected +5% price move - โ†“ (100ms) -TradeExecutor โ†’ Places BUY order on Kalshi - โ†“ (200ms) -Total Time: ~615ms (before other traders react!) -``` - ---- - -## Basic Operations - -### Starting Individual Components - -```bash -# Just weather monitoring -python -m src.sdk.adapters.weather - -# Just DraftKings odds -python -m src.sdk.adapters.draftkings - -# Just Reddit sentiment -python -m src.sdk.adapters.reddit -``` - -### Monitoring System Health - -```bash -# Check Redis messages -redis-cli MONITOR - -# See active channels -redis-cli PUBSUB CHANNELS - -# Count messages in a channel -redis-cli PUBSUB NUMSUB kalshi:markets -``` - -### Running Tests - ```bash -# Test SDK functionality -python scripts/test_sdk.py - -# Test specific adapter -python -c " -from src.sdk import SDKManager -import asyncio - -async def test(): - sdk = SDKManager() - await sdk.initialize() - results = await sdk.test_adapter('draftkings', duration=10) - print(f'Events received: {results[\"events_received\"]}') - -asyncio.run(test()) -" -``` - ---- - -## Common Configurations - -### Focus on Specific Games - -To monitor only specific games, configure your sources: - -```yaml -# config/data_sources.yaml -sources: - - name: draftkings - config: - sports: - - NFL - teams: # Optional: focus on specific teams - - "Kansas City Chiefs" - - "Buffalo Bills" -``` - -### Adjust Update Frequencies - -```yaml -sources: - - name: draftkings - config: - poll_interval: 2 # Check every 2 seconds (was 5) - - - name: weather - config: - update_interval: 60 # Check every minute (was 5 minutes) +pip install neural-sdk ``` -### Set Trading Thresholds - -```yaml -# config/trading_config.yaml -thresholds: - min_edge: 0.03 # 3% minimum advantage - min_confidence: 0.75 # 75% confidence required - max_position: 0.05 # 5% of capital max per trade -``` - ---- - -## Troubleshooting +## Quick Start -### No Events Showing Up? +1. **Set up environment variables** +2. **Create your first strategy** +3. **Run a backtest** +4. **Deploy live trading** (optional) -1. **Check Redis is running:** -```bash -redis-cli ping -# Should return PONG -``` - -2. **Verify API credentials:** -```bash -# Test weather API -curl "https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_KEY" -``` - -3. **Enable debug logging:** -```python -# Add to your script -import logging -logging.basicConfig(level=logging.DEBUG) -``` - -### Events But No Trading? - -1. **Check Kalshi connection:** -```bash -python examples/test_kalshi_websocket.py -``` - -2. **Verify market is open:** -- Sports markets only trade during games -- Check Kalshi website for active markets - -3. **Review thresholds:** -- Your edge threshold might be too high -- Lower confidence requirement for testing - -### High Latency? - -1. **Check network:** -```bash -ping api.kalshi.com -``` - -2. **Reduce data sources:** -- Start with just one source -- Add more gradually - -3. **Optimize Redis:** -```bash -# Check Redis latency -redis-cli --latency -``` - ---- +For detailed instructions, see the main README.md. ## Next Steps -### 1. Add More Data Sources - -Create your own adapter in under 50 lines: - -```python -from src.sdk import DataSourceAdapter, StandardizedEvent, EventType - -class MyAdapter(DataSourceAdapter): - async def connect(self): - # Your connection logic - return True - - async def stream(self): - while self.is_connected: - # Your data fetching - data = await self.fetch() - yield StandardizedEvent( - source="MySource", - event_type=EventType.CUSTOM, - data=data - ) -``` - -### 2. Customize Trading Logic - -Modify agents to implement your strategy: - -```python -# agents/StrategyAnalyst/agent.py -@tool -def my_custom_strategy(market_data, weather, sentiment): - # Your alpha generation logic - if weather['wind_speed'] > 20 and market_data['spread'] > 3: - return {"action": "buy", "confidence": 0.85} -``` - -### 3. Set Up Production Monitoring - -```bash -# Run with full logging -python examples/production_monitor.py - -# Set up alerts -python scripts/setup_alerts.py --email your@email.com -``` - ---- - -## Essential Commands - -```bash -# Development -python scripts/demo_sdk.py # Test SDK -python examples/agent_redis_consumer.py # Run consumers -redis-cli MONITOR # Watch Redis - -# Testing -pytest tests/ # Run all tests -pytest tests/test_sdk.py -v # Test SDK only - -# Production -python -m src.data_pipeline.orchestration.unified_stream_manager # Start streams -python agents/launch_all.py # Start all agents -python scripts/monitor_health.py # Health dashboard -``` - ---- - -## Getting Help - -If you run into issues: - -1. Check the logs in `logs/` directory -2. Review configuration in `config/` -3. Run diagnostic script: `python scripts/diagnose.py` -4. See troubleshooting guide in docs - -Remember: Start simple with one data source, verify it works, then add complexity! - ---- - -## Ready to Trade? - -You're now ready to: -- โœ… Stream real-time data -- โœ… Process events through the pipeline -- โœ… Generate trading signals -- โœ… Execute on Kalshi markets - -Next: Read [DATA_SOURCES_GUIDE.md](DATA_SOURCES_GUIDE.md) to understand each data source in detail. \ No newline at end of file +- [API Reference](api_reference.md) - Complete SDK documentation +- [Backtesting Guide](backtesting.md) - Historical testing framework +- [Data Sources](data_sources.md) - Setting up data feeds +- [Strategy Development](strategies.md) - Building trading algorithms \ No newline at end of file diff --git a/docs/GITHUB_PUSH_GUIDE.md b/docs/GITHUB_PUSH_GUIDE.md deleted file mode 100644 index c716a620..00000000 --- a/docs/GITHUB_PUSH_GUIDE.md +++ /dev/null @@ -1,467 +0,0 @@ -# GitHub Push Guide - -## Pre-Push Checklist - -### 1. Verify Local Setup -```bash -# Check git is initialized -git status - -# Verify remote is not set yet -git remote -v - -# Ensure you're on main branch -git branch -``` - -### 2. Clean Sensitive Data -```bash -# Ensure .env is in .gitignore -grep "^\.env$" .gitignore - -# Check for any secrets in code -grep -r "KALSHI_API_KEY" --exclude-dir=.git --exclude=.env* . -grep -r "OPENROUTER_API_KEY" --exclude-dir=.git --exclude=.env* . -grep -r "AGENTUITY_SDK_KEY" --exclude-dir=.git --exclude=.env* . - -# Verify no credentials in committed files -git diff --cached | grep -i "api_key\|secret\|password\|token" -``` - -### 3. Verify Documentation -```bash -# Check all required docs exist -ls -la README.md CLAUDE.md CONTRIBUTING.md -ls -la docs/ -ls -la .github/ -``` - -## Initial Repository Setup - -### Step 1: Create GitHub Repository - -1. Go to https://github.com/new -2. Repository settings: - - **Name**: `Kalshi_Agentic_Agent` - - **Description**: "Autonomous multi-agent trading system for Kalshi sports event contracts" - - **Visibility**: Private (initially) - - **DO NOT** initialize with README, .gitignore, or license - -### Step 2: Initialize Local Repository - -```bash -# If not already initialized -git init - -# Add GitHub remote -git remote add origin https://github.com/YOUR_USERNAME/Kalshi_Agentic_Agent.git - -# Verify remote -git remote -v -``` - -### Step 3: Prepare Initial Commit - -```bash -# Stage all files -git add . - -# Verify what's being staged -git status - -# Check file count -git ls-files | wc -l - -# Create initial commit -git commit -m "feat: initial commit - production-ready multi-agent trading system - -- Complete repository structure with clear naming conventions -- Comprehensive CI/CD pipeline with GitHub Actions -- Full documentation suite (README, CLAUDE.md, CONTRIBUTING.md) -- Redis-based agent communication architecture -- Agentuity framework integration -- Kelly Criterion trading logic implementation -- WebSocket data pipeline for real-time processing -- PostgreSQL database with Alembic migrations -- Security scanning and automated testing -- Docker containerization support" -``` - -### Step 4: Push to GitHub - -```bash -# Push main branch -git push -u origin main - -# Create and push develop branch -git checkout -b develop -git push -u origin develop - -# Return to main -git checkout main -``` - -## Configure GitHub Repository - -### Step 1: Set Up Secrets - -Navigate to: Settings โ†’ Secrets and variables โ†’ Actions - -Add the following secrets: - -#### Required Secrets -```yaml -# Kalshi Trading -KALSHI_API_KEY_ID: "your-kalshi-api-key-id" -KALSHI_PRIVATE_KEY: | - -----BEGIN PRIVATE KEY----- - your-private-key-content - -----END PRIVATE KEY----- -KALSHI_ENVIRONMENT: "production" # or "demo" for testing - -# AI/LLM -OPENROUTER_API_KEY: "your-openrouter-api-key" - -# Agentuity Platform -AGENTUITY_SDK_KEY: "your-agentuity-sdk-key" - -# Infrastructure -REDIS_URL: "redis://your-redis-host:6379" - -# Optional - for deployment -DOCKER_REGISTRY: "your-docker-registry" -DOCKER_USERNAME: "your-docker-username" -DOCKER_PASSWORD: "your-docker-password" -``` - -### Step 2: Configure Environments - -Navigate to: Settings โ†’ Environments - -Create two environments: - -#### Staging Environment -- **Name**: staging -- **Protection rules**: - - Only from: `develop` branch - - Required reviewers: 1 -- **Secrets**: Add staging-specific overrides - -#### Production Environment -- **Name**: production -- **Protection rules**: - - Only from: `main` branch - - Required reviewers: 2 - - Restrict deployments to specific users -- **Secrets**: Add production-specific values - -### Step 3: Enable Branch Protection - -Navigate to: Settings โ†’ Branches - -#### Main Branch Protection -```bash -# Using GitHub CLI (if installed) -gh api repos/:owner/:repo/branches/main/protection \ - --method PUT \ - --field required_status_checks='{"strict":true,"contexts":["CI Pipeline / Lint & Format Check","CI Pipeline / Test Suite","CI Pipeline / Security Scan","CI Pipeline / Build & Validate"]}' \ - --field required_pull_request_reviews='{"required_approving_review_count":2,"dismiss_stale_reviews":true}' \ - --field enforce_admins=true \ - --field allow_force_pushes=false \ - --field allow_deletions=false -``` - -Or manually: -1. Click "Add rule" -2. Branch name pattern: `main` -3. Enable: - - โœ… Require pull request before merging (2 approvals) - - โœ… Require status checks to pass - - โœ… Require branches to be up to date - - โœ… Include administrators - - โœ… Restrict who can push (only maintainers) - -#### Develop Branch Protection -Similar to main but with 1 required approval. - -### Step 4: Configure GitHub Pages (Optional) - -For documentation hosting: - -1. Settings โ†’ Pages -2. Source: Deploy from branch -3. Branch: main -4. Folder: /docs -5. Save - -### Step 5: Set Up Teams (If Organization) - -1. Settings โ†’ Manage access โ†’ Invite teams -2. Create teams: - - `maintainers` - Admin access - - `developers` - Write access - - `qa-team` - Triage access - -### Step 6: Configure Webhooks (Optional) - -For external integrations: - -1. Settings โ†’ Webhooks โ†’ Add webhook -2. Payload URL: Your monitoring service -3. Events: Push, Pull Request, Deployment - -## Verify CI/CD Pipeline - -### Step 1: Create Test PR - -```bash -# Create feature branch -git checkout -b feature/test-ci -echo "# Test CI" > test.md -git add test.md -git commit -m "test: verify CI pipeline" -git push -u origin feature/test-ci -``` - -### Step 2: Open Pull Request - -1. Go to repository on GitHub -2. Click "Compare & pull request" -3. Target: develop -4. Create pull request - -### Step 3: Verify Checks - -Ensure all checks pass: -- โœ… Lint & Format Check -- โœ… Test Suite -- โœ… Security Scan -- โœ… Build & Validate -- โœ… PR Checks - -### Step 4: Clean Up - -```bash -# After merge, delete test branch -git checkout develop -git pull origin develop -git branch -d feature/test-ci -git push origin --delete feature/test-ci -``` - -## First Deployment - -### Step 1: Prepare for Deployment - -```bash -# Ensure on develop branch -git checkout develop - -# Tag release candidate -git tag -a v0.1.0-rc.1 -m "Release candidate 1 for v0.1.0" -git push origin v0.1.0-rc.1 -``` - -### Step 2: Deploy to Staging - -```bash -# Trigger staging deployment -# This happens automatically on push to develop - -# Or manually via GitHub Actions -gh workflow run deploy.yml -f environment=staging -f version=v0.1.0-rc.1 -``` - -### Step 3: Production Release - -```bash -# Create release PR -git checkout -b release/v0.1.0 -git push -u origin release/v0.1.0 - -# After approval and merge to main -git checkout main -git pull origin main -git tag -a v0.1.0 -m "Initial release v0.1.0" -git push origin v0.1.0 - -# Create GitHub Release -gh release create v0.1.0 \ - --title "v0.1.0 - Initial Release" \ - --notes "Initial production release of Kalshi Trading Agent System" \ - --target main -``` - -## Post-Push Tasks - -### Immediate Actions - -1. **Verify Repository Access**: - ```bash - # Clone in new directory to test - cd /tmp - git clone https://github.com/YOUR_USERNAME/Kalshi_Agentic_Agent.git - cd Kalshi_Agentic_Agent - ``` - -2. **Check CI Status**: - - Go to Actions tab - - Verify workflows are detected - - Check for any configuration errors - -3. **Update README Badge**: - ```markdown - ![CI Pipeline](https://github.com/YOUR_USERNAME/Kalshi_Agentic_Agent/workflows/CI%20Pipeline/badge.svg) - ``` - -### Within 24 Hours - -1. **Security Scan**: - - Enable Dependabot alerts - - Review security recommendations - - Set up code scanning - -2. **Documentation**: - - Verify all links work - - Check rendered markdown - - Update any absolute paths - -3. **Team Access**: - - Invite collaborators - - Set up CODEOWNERS file - - Configure notifications - -### Within First Week - -1. **Monitoring Setup**: - - Configure error tracking - - Set up performance monitoring - - Add deployment notifications - -2. **Backup Strategy**: - - Set up repository mirroring - - Configure automated backups - - Document recovery procedures - -3. **Performance Baseline**: - - Run initial load tests - - Document response times - - Set up metrics collection - -## Troubleshooting - -### Common Issues - -#### Push Rejected - Large Files -```bash -# Check for large files -find . -type f -size +100M - -# Add to .gitignore if needed -echo "large-file.bin" >> .gitignore - -# Remove from git history -git filter-branch --index-filter 'git rm --cached --ignore-unmatch large-file.bin' HEAD -``` - -#### Push Rejected - Credentials Detected -```bash -# Remove sensitive data -git filter-branch --force --index-filter \ - 'git rm --cached --ignore-unmatch path/to/sensitive-file' \ - --prune-empty --tag-name-filter cat -- --all -``` - -#### CI Workflows Not Triggering -1. Check workflow syntax -2. Verify file location (.github/workflows/) -3. Ensure proper permissions -4. Check branch protection settings - -#### Permission Denied -```bash -# For HTTPS -git config --global credential.helper cache - -# For SSH -ssh-add ~/.ssh/id_rsa -``` - -## Security Checklist - -Before making repository public: - -- [ ] All secrets in GitHub Secrets -- [ ] No hardcoded credentials -- [ ] .env.example has placeholder values -- [ ] Security scanning enabled -- [ ] Dependency review enabled -- [ ] Branch protection configured -- [ ] CODEOWNERS file created -- [ ] Security policy added -- [ ] Vulnerability reporting enabled - -## Quick Reference - -### Essential Commands -```bash -# Initial push -git push -u origin main - -# Create develop branch -git checkout -b develop -git push -u origin develop - -# Create feature branch -git checkout -b feature/new-feature -git push -u origin feature/new-feature - -# Update from upstream -git fetch origin -git merge origin/develop - -# Tag release -git tag -a v1.0.0 -m "Release v1.0.0" -git push origin v1.0.0 -``` - -### GitHub CLI Commands -```bash -# Check workflow runs -gh run list - -# View workflow details -gh run view - -# Watch workflow in progress -gh run watch - -# List issues -gh issue list - -# Create issue -gh issue create --title "Bug report" --body "Description" - -# List PRs -gh pr list - -# Create PR -gh pr create --title "Feature" --body "Description" -``` - -## Next Steps - -After successful push: - -1. **Test the CI pipeline** with a small PR -2. **Configure deployment** to Agentuity platform -3. **Set up monitoring** and alerting -4. **Document API endpoints** if applicable -5. **Create initial issues** for known improvements -6. **Invite team members** and assign roles -7. **Schedule regular dependency updates** -8. **Plan first sprint** using GitHub Projects - ---- - -Remember: This is a financial trading system. Ensure all security measures are properly configured before deploying to production. \ No newline at end of file diff --git a/docs/GIT_WORKFLOW.md b/docs/GIT_WORKFLOW.md deleted file mode 100644 index ff781fc5..00000000 --- a/docs/GIT_WORKFLOW.md +++ /dev/null @@ -1,443 +0,0 @@ -# Git Workflow & Branching Strategy - -## Branch Structure - -``` -main (production) - โ”œโ”€โ”€ develop (integration) - โ”‚ โ”œโ”€โ”€ feature/feature-name - โ”‚ โ”œโ”€โ”€ bugfix/issue-description - โ”‚ โ””โ”€โ”€ hotfix/critical-fix - โ””โ”€โ”€ release/v1.0.0 -``` - -## Branch Types - -### 1. Main Branch (`main`) -- **Purpose**: Production-ready code -- **Protection**: Full protection enabled -- **Deploy**: Automatically to production -- **Merge**: Only from `release/*` or `hotfix/*` branches -- **Requirements**: - - All tests passing - - Code review approved - - No merge conflicts - -### 2. Develop Branch (`develop`) -- **Purpose**: Integration branch for features -- **Protection**: Requires PR and tests -- **Deploy**: To staging environment -- **Merge**: From `feature/*` and `bugfix/*` branches -- **Updated**: Daily from `main` - -### 3. Feature Branches (`feature/*`) -- **Naming**: `feature/description-of-feature` -- **Created from**: `develop` -- **Merged to**: `develop` -- **Lifetime**: Until feature complete -- **Examples**: - - `feature/add-stop-loss-monitor` - - `feature/espn-api-integration` - - `feature/kelly-criterion-update` - -### 4. Bugfix Branches (`bugfix/*`) -- **Naming**: `bugfix/issue-number-description` -- **Created from**: `develop` -- **Merged to**: `develop` -- **Lifetime**: Until bug fixed -- **Examples**: - - `bugfix/123-websocket-reconnection` - - `bugfix/456-redis-timeout` - -### 5. Release Branches (`release/*`) -- **Naming**: `release/vX.Y.Z` -- **Created from**: `develop` -- **Merged to**: `main` and back to `develop` -- **Purpose**: Final testing and version prep -- **Allowed changes**: Bug fixes only - -### 6. Hotfix Branches (`hotfix/*`) -- **Naming**: `hotfix/critical-issue` -- **Created from**: `main` -- **Merged to**: `main` and `develop` -- **Purpose**: Emergency production fixes -- **Review**: Expedited process - -## Workflow Steps - -### Starting New Feature - -```bash -# 1. Update develop branch -git checkout develop -git pull origin develop - -# 2. Create feature branch -git checkout -b feature/my-new-feature - -# 3. Work on feature -git add . -git commit -m "feat: add new feature description" - -# 4. Push to remote -git push -u origin feature/my-new-feature - -# 5. Create Pull Request to develop -``` - -### Creating a Release - -```bash -# 1. Create release branch from develop -git checkout develop -git pull origin develop -git checkout -b release/v1.0.0 - -# 2. Update version numbers -# Update pyproject.toml, README.md, etc. - -# 3. Final testing and fixes -git add . -git commit -m "chore: prepare release v1.0.0" - -# 4. Merge to main -git checkout main -git merge --no-ff release/v1.0.0 -git tag -a v1.0.0 -m "Release version 1.0.0" - -# 5. Merge back to develop -git checkout develop -git merge --no-ff release/v1.0.0 - -# 6. Push everything -git push origin main develop --tags - -# 7. Delete release branch -git branch -d release/v1.0.0 -git push origin --delete release/v1.0.0 -``` - -### Emergency Hotfix - -```bash -# 1. Create hotfix from main -git checkout main -git pull origin main -git checkout -b hotfix/critical-bug - -# 2. Fix the issue -git add . -git commit -m "hotfix: fix critical production bug" - -# 3. Merge to main -git checkout main -git merge --no-ff hotfix/critical-bug -git tag -a v1.0.1 -m "Hotfix version 1.0.1" - -# 4. Merge to develop -git checkout develop -git merge --no-ff hotfix/critical-bug - -# 5. Push and cleanup -git push origin main develop --tags -git branch -d hotfix/critical-bug -git push origin --delete hotfix/critical-bug -``` - -## Commit Message Convention - -### Format -``` -(): - - - -