SpaceX Conversational Agent

Multi-agent system that answers questions about SpaceX using data from the SpaceX API. Built with Python and Haystack framework.

Quick Start

1. Set up virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies

   pip install -r requirements.txt

3. Set up environment

   # Create .env file and add your OPENAI_API_KEY
   # OPENAI_API_KEY=sk-...

4. Run the agent

   python main.py --silent    # Clean output without logs
   python main.py             # With logs
   python main.py --verbose   # Debug mode

Multi-Agent Architecture

Three specialized agents following Haystack patterns:

         SupervisorAgent
              |
    +---------+---------+
    |                   |
DataExtractionAgent  ComputationAgent
  (7 API tools)      (2 calc tools)

1. SupervisorAgent: Routes queries to appropriate specialized agents and coordinates data flow
2. DataExtractionAgent: Handles SpaceX API calls and data retrieval (7 tools)
3. ComputationAgent: Performs calculations and analysis on SpaceX data provided by supervisor (2 tools)

Available Tools

Data Extraction (via DataExtractionAgent):

• get_last_launch() - Most recent launch
• get_next_launch() - Upcoming launch
• filter_launches() - Filter by status, rocket, year
• count_launches() - Count launches by criteria
• search_missions() - Search by name/keyword
• get_rocket_info() - Rocket specifications
• compare_rockets() - Compare multiple rockets

Computation (via ComputationAgent - works on data provided by supervisor):

• execute_python_code() - Execute Python for analysis (pandas, numpy) on SpaceX data
• calculate_statistics() - Calculate mean, median, std dev, min, max on numeric data

Note: ComputationAgent does not fetch SpaceX data directly. The SupervisorAgent coordinates by:

1. Using DataExtractionAgent to fetch SpaceX data
2. Passing that data to ComputationAgent for calculations
3. Synthesizing results into a coherent answer

Example Queries

Data Retrieval:

• When was the last SpaceX launch?
• Tell me about the Starlink 9-1 mission
• Show me all upcoming launches
• Compare the payload capacity of Falcon 9 vs Falcon Heavy

Calculations & Analysis (requires both agents):

• What's the success rate of Falcon 9 launches in 2024?
• Calculate the average time between launches this year
• What's the total estimated cost of all Starlink missions?
• How many launches did SpaceX do per month in 2023?

Design Highlights

• Agentic Patterns: Multi-step reasoning, tool orchestration, clarifying questions
• Type Safety: Pydantic models with validation
• Error Handling: Retry logic, graceful degradation, explicit error guidance in prompts
• Clean Architecture: Separation of concerns (agent/tools/api/models/ui)
• Datetime Aware: Agents understand time-relative queries ("recent", "this year")
• Input Validation: Tool parameters validated (year ranges, status values, limits)
• Rate Limiting: API calls limited to 50 requests/minute to respect API limits
• Structured Comparisons: Rocket comparison returns side-by-side structured data
• Production Logging: Silent mode logs to file while suppressing console output

Testing

Comprehensive test suite with 96 tests covering:

• Agent Tests: Unit tests for supervisor, data extraction, and computation agents (21 tests)
• API Client Tests: Timeouts, retries, malformed responses, rate limiting (16 tests)
• Conversation Tests: History management, turn counting, context summaries (15 tests)
• Tool Tests: Edge cases (empty results, null fields), input validation (26 tests)
• Model Tests: Launch and rocket model validation (8 tests)
• Code Execution Tests: Python execution, statistics, security checks (10 tests)

pytest tests/              # Run all tests
pytest tests/ -v           # Verbose output
pytest tests/ -k "agent"   # Run only agent tests
pytest tests/ -k "api"     # Run only API tests

Project Structure

spaceX-agent/
├── agent/
│   ├── supervisor_agent.py      # Main coordinator
│   ├── data_agent.py            # SpaceX API specialist
│   ├── computation_agent.py     # Calculation specialist
│   ├── prompts.py               # Agent prompts with datetime
│   └── conversation.py          # History manager
├── tools/                       # Haystack @tool functions
│   ├── launch_tools.py          # Launch querying tools
│   ├── rocket_tools.py          # Rocket info & comparison
│   ├── mission_tools.py         # Mission search
│   └── code_execution.py        # Python execution & stats
├── api/                         # SpaceX API client
│   ├── client.py                # Rate-limited API client
│   └── exceptions.py            # Custom exceptions
├── models/                      # Pydantic models
│   ├── launch.py                # Launch model
│   └── rocket.py                # Rocket model
├── ui/                          # CLI interface
│   └── cli.py                   # Command-line interface
├── tests/                       # Unit tests (100+ tests)
│   ├── test_agents.py           # Existing agent tests
│   ├── test_computation_agent.py # New: ComputationAgent tests
│   ├── test_supervisor_agent.py  # New: SupervisorAgent tests
│   ├── test_conversation.py     # New: Conversation tests
│   ├── test_api_client.py       # Enhanced API tests
│   └── test_tools.py            # Enhanced tool tests
├── logs/                        # Application logs (auto-created)
├── .env                         # Environment configuration
├── requirements.txt             # Python dependencies
└── README.md                    # This file

Key Implementation Details

• Uses Haystack's ComponentTool to wrap agents as tools for the supervisor
• Sub-agents use temperature=0.0 for deterministic behavior
• Supervisor uses temperature=0.7 for natural conversation
• All API data parsed into typed Pydantic models
• Tools return structured dictionaries with explicit error handling
• Rate limiting: 50 API requests per minute with automatic retry
• Input validation on all tool parameters (years, statuses, limits)
• Structured rocket comparisons with side-by-side field arrays
• File-based logging in silent mode for production debugging

Logging

Application logs are written to logs/spacex_agent.log:

• Normal mode (python main.py): Logs to console + file
• Silent mode (python main.py --silent): Logs to file only (warnings/errors)
• Verbose mode (python main.py --verbose): Debug-level logging

The logs/ directory is automatically created and excluded from version control.