README

Overview

BILL AI is a sophisticated autonomous agent system featuring a cocky crypto trading influencer personality. The system implements advanced multi-platform coordination, intelligent context management, and autonomous operation capabilities across Twitter, Telegram, and web interfaces.

Current Architecture

The project has evolved significantly from its initial design, now featuring:

• Workflow-Based Agent Runtime: Plan & Execute pattern with multi-stage LLM pipelines

• Advanced Context Management: Platform-specific context managers with LLM-based analysis

• Multi-Tool Integration: Financial data, news, web search, and social media monitoring

• Autonomous Operation: Event-driven posting with real-time market awareness

• Multi-Platform Support: Twitter, Telegram, and Website with unified character consistency

System Components

Core Agent Runtime (agent/)

• Workflow Manager: Orchestrates multi-stage LLM pipelines (planning → context → response → fallback)

• Tool System: Extensible tool framework with financial APIs, news, and web search

• Character System: BILL personality management with platform-specific templates

• Context Management: Sophisticated context aggregation and analysis

• Service Layer: LLM routing (OpenRouter, OpenAI) with intelligent fallback mechanisms

Platform Integrations

Twitter Plugin (agent/plugins/twitter/)

• Autonomous Posting: Context-aware tweet generation with market monitoring

• Timeline Monitoring: Continuous ingestion from influential accounts

• Image Analysis: GPT-4 Vision for screenshot and image understanding

• Event-Driven Responses: Real-time reactions to market events

• Advanced Caching: Supabase-based conversation and timeline storage

Telegram Plugin (agent/plugins/telegram/)

• Bot Integration: Full Telegram Bot API support

• Multi-Context Support: Private chats, groups, and channels

• Webhook/Polling: Flexible deployment options

• Character Consistency: BILL personality across all chat types

Website Client (clients/website/)

• Real-time Chat: WebSocket-based chat interface

• Matrix UI: Cyberpunk-themed terminal interface

• Security: reCAPTCHA v3 integration

• Claims Portal: Airdrop claims functionality

• Debug Logging: Production-safe logging system

Supporting Infrastructure

API Server (clients/bill-api-server/)

• WebSocket Server: Real-time communication hub

• Agent Integration: Direct connection to BILL agent runtime

• Security Middleware: CAPTCHA verification and rate limiting

Logging UI (clients/logging-ui/)

• Real-time Monitoring: WebSocket-based log streaming

• Workflow Visualization: Multi-stage LLM call tracking

• Debug Interface: Development and production debugging

Key Innovations

1. Workflow System

The agent now uses a sophisticated workflow pipeline:

User Input → Planning (Intent Analysis) → Context Enrichment → Tool Execution → Response Generation → Fallback Handling

2. Context Analysis Engine

Platform-specific context managers that aggregate multiple data sources:

• Twitter timeline monitoring

• News API integration (planned)

• Market data feeds (planned)

• LLM-based neutral analysis for factual summaries

3. Tool Ecosystem

Comprehensive tool suite for BILL's market awareness:

• Web Search: Google search integration

• News Tool: NewsAPI.org for categorized news

• Crypto Prices: Real-time cryptocurrency data

• Stock Data: Yahoo Finance integration

• Twitter Timeline: Monitored accounts database

• Time Tool: Market hours and timing

4. Autonomous Posting System

Event-driven posting with sophisticated triggers:

• Breaking news detection

• Market movement reactions

• Fed event responses

• Earnings announcements

• Crypto market shifts

Development Status

✅ Completed Features

• Core agent runtime with workflow support

• Twitter plugin with full autonomous capabilities

• Telegram bot integration

• Website client with real-time chat

• Character system with BILL personality

• Multi-model LLM support (Claude, GPT-4, Gemini)

• Image analysis pipeline

• Context management system

• Tool framework with 6+ tools

• Production logging and monitoring

🚧 In Progress

• News API integration

• Market data feeds

• Reddit/Discord monitoring

• Enhanced memory system

• Cross-platform conversation continuity

📋 Planned Features

• Voice integration

• Advanced trading signals

• Community management tools

• Analytics dashboard

• Multi-agent coordination

Technical Stack

• Runtime: Bun (not Node.js/npm)

• Language: TypeScript

• Database: Supabase (PostgreSQL + Storage)

• LLM Providers: OpenRouter (Claude, GPT-4, Gemini), OpenAI (GPT-4o Vision)

• Frontend: Next.js 15, React 19, Tailwind CSS

• Deployment: Railway (API), Vercel (Website)

Getting Started

See DEVELOPMENT_SETUP.md for detailed setup instructions.

Documentation Structure

• 01_agent/ - Core agent architecture and services

• 02_clients/ - Platform integration documentation

• 03_development-guides/ - Development guides and best practices

• 04_design-proposals/ - Original design documents (historical)

Recent Major Updates

1. Workflow System: Complete rewrite of agent runtime to support multi-stage pipelines

2. Context Analysis: LLM-based context analysis replacing keyword matching

3. Event-Driven Posting: Autonomous posting based on real-time events

4. Tool Integration: 6+ specialized tools for market awareness

5. Production Hardening: Safe logging, error handling, and monitoring

For detailed information about specific components, refer to the documentation in each section.