ElixirScope: AI-Powered Execution Cinema Debugger for Elixir

ElixirLicense: MIT

ElixirScope is a next-generation debugging and observability platform for Elixir applications, designed to provide an "Execution Cinema" experience through deep, compile-time AST instrumentation guided by AI-powered analysis.

🎬 Try the Cinema Demo Now!

Experience ElixirScope in action with our comprehensive working demo:

git clone https://github.com/your-org/elixir_scope.git
cd elixir_scope/test_apps/cinema_demo
./run_showcase.sh

✨ See all features working in ~1 minute: Time-travel debugging, performance monitoring, state reconstruction, and more!

[📖 Complete Demo Documentation →](https://github.com/nshkrdotcom/ElixirScope/blob/main/test_apps/cinema_demo/FULLY_BLOWN.md

🎯 Vision & Mission

Transform Elixir development by providing unprecedented insight into application behavior through:

🚀 Current Implementation Status

ElixirScope has achieved major milestones with a comprehensive working demo and core components fully operational:

🎬 NEW: Complete Cinema Demo Available!

✅ FULLY WORKING SHOWCASE - Experience all ElixirScope features in action:

cd test_apps/cinema_demo
./run_showcase.sh

What you'll see:

📖 See FULLY_BLOWN.md for complete demo documentation

✅ Production-Ready Components

Core Infrastructure (100% Complete)

Data Capture Pipeline (95% Complete)

AST Transformation Engine (90% Complete)

AI Analysis Framework (85% Complete)

Cinema Debugger System (90% Complete)

AST Repository System (85% Complete)

Compile-Time Orchestration (80% Complete)

📋 Planned Features

Web Interface (Next Priority)

Advanced Integrations (Future)

🏗️ Architecture Overview

ElixirScope follows a compile-time first approach with runtime correlation capabilities:

graph TD
    subgraph "Developer Tools"
        IDE["IDE / IEx"]
        MixTask["Mix Tasks (Planned)"]
    end

    subgraph "AI Analysis Engine"
        Orchestrator["AI.Orchestrator ✅"]
        CodeAnalyzer["Code Analyzer ✅"]
        PatternRecognizer["Pattern Recognizer ✅"]
        LLMProviders["LLM Providers ✅<br/>Gemini • Vertex • Mock"]
    end

    subgraph "AST Transformation"
        Transformer["AST.Transformer ✅"]
        EnhancedTransformer["Enhanced Transformer ✅"]
        CompileTime["Compile-Time Orchestrator 🚧"]
    end

    subgraph "Data Capture Pipeline"
        Runtime["InstrumentationRuntime ✅"]
        Ingestor["Ingestor ✅"]
        RingBuffer["Ring Buffer ✅"]
        Pipeline["Pipeline Manager ✅"]
        Storage["Data Access ✅"]
    end

    subgraph "Cinema Debugger System"
        TemporalStorage["TemporalStorage ✅"]
        TemporalBridge["TemporalBridge ✅"]
        StateReconstruction["State Reconstruction ✅"]
    end

    subgraph "AST Repository"
        Repository["Repository Core ✅"]
        FunctionData["Function Data ✅"] 
        Correlator["Runtime Correlator ✅"]
    end

    IDE --> Orchestrator
    Orchestrator --> CodeAnalyzer
    CodeAnalyzer --> LLMProviders
    CodeAnalyzer --> Transformer
    Transformer --> Runtime
    Runtime --> Ingestor
    Ingestor --> RingBuffer
    RingBuffer --> Pipeline
    Pipeline --> Storage
    Storage --> TemporalStorage
    TemporalStorage --> TemporalBridge
    TemporalBridge --> StateReconstruction
    Repository --> Correlator
    Correlator --> TemporalBridge
    
    style Runtime fill:#c8e6c9,color:#000
    style Ingestor fill:#c8e6c9,color:#000
    style Orchestrator fill:#e1f5fe,color:#000
    style Repository fill:#fff3e0,color:#000
    style TemporalBridge fill:#c8e6c9,color:#000
    style StateReconstruction fill:#c8e6c9,color:#000

Key Architectural Principles

🚀 Getting Started

Installation

Add ElixirScope to your mix.exs:

def deps do
  [
    {:elixir_scope, "~> 0.1.0"}
  ]
end

Basic Configuration

# config/config.exs
config :elixir_scope,
  # Data capture settings
  capture: [
    buffer_size: 10_000,
    batch_size: 100,
    flush_interval: 1_000
  ],
  
  # AI analysis settings  
  ai: [
    llm_provider: :mock,  # :gemini, :vertex, :mock
    analysis_timeout: 30_000,
    planning: [
      default_strategy: :balanced
    ]
  ],
  
  # AST instrumentation settings
  ast: [
    default_instrumentation_level: :function_boundaries,
    performance_monitoring: true,
    variable_capture: false
  ]

Quick Start - Try the Cinema Demo!

The fastest way to experience ElixirScope is through our comprehensive demo:

# Clone the repository
git clone https://github.com/nshkrdotcom/ElixirScope.git elixir_scope
cd elixir_scope

# Run the complete showcase
cd test_apps/cinema_demo
./run_showcase.sh

This will demonstrate:

Current Usage Examples

Main Application API

# Start ElixirScope with your application
children = [
  # Your application children...
  {ElixirScope, []}
]

# Use the main API
ElixirScope.start(strategy: :full_trace, sampling_rate: 1.0)
status = ElixirScope.status()

# Check if running
ElixirScope.running?()
# => true

# Update configuration at runtime
ElixirScope.update_config([:ai, :planning, :sampling_rate], 0.5)

Cinema Debugger Features

# Start TemporalBridge for time-travel debugging
{:ok, bridge} = ElixirScope.Capture.TemporalBridge.start_link(
  name: :my_bridge,
  buffer_size: 1000
)

# Get bridge statistics
{:ok, stats} = ElixirScope.Capture.TemporalBridge.get_stats(bridge)

# Reconstruct state at specific timestamp
{:ok, past_state} = ElixirScope.Capture.TemporalBridge.reconstruct_state_at(
  bridge, 
  timestamp
)

AI-Powered Code Analysis

# Analyze code with AI
{:ok, analysis} = ElixirScope.AI.CodeAnalyzer.analyze_module(MyModule)

# Generate instrumentation plan
{:ok, plan} = ElixirScope.AI.Orchestrator.plan_for_module(source_code)

# Recognize patterns
patterns = ElixirScope.AI.PatternRecognizer.extract_patterns(ast)

LLM Provider Setup

Google Gemini API

export GOOGLE_API_KEY="your-gemini-api-key"
config :elixir_scope, ai: [llm_provider: :gemini]

Vertex AI

export VERTEX_JSON_FILE="/path/to/service-account.json"
config :elixir_scope, ai: [llm_provider: :vertex]

🧪 Testing & Development

ElixirScope has comprehensive testing with 723 tests passing, 0 failures and extensive coverage across all components.

Test Commands

# Default test command - excludes live API tests, shows full test names
mix test

# All tests including live API tests (may hang without API keys)
mix test.all

# Fast tests (parallelized)  
mix test.fast

# LLM provider tests
mix test.mock          # Mock provider only
mix test.gemini        # Live Gemini API tests
mix test.vertex        # Live Vertex AI tests
mix test.live          # All live API tests

# Legacy alias (same as default mix test)
mix test.trace

# Performance validation
mix test.performance

Cinema Demo Testing

# Test the complete demo application
cd test_apps/cinema_demo
mix test

# Run individual demo scenarios
mix run -e "CinemaDemo.run_task_management_demo()"
mix run -e "CinemaDemo.run_time_travel_debugging_demo()"

# Run the complete showcase
./run_showcase.sh

Live API Testing

To run tests against real LLM APIs:

# Set up credentials
export GOOGLE_API_KEY="your-key"
export VERTEX_JSON_FILE="/path/to/service-account.json"

# Run live tests
mix test.live

📊 Performance Characteristics

Current Benchmarks

Component Performance Status
InstrumentationRuntime <100µs per event ✅ Production Ready
TemporalBridge <100µs event forwarding ✅ Production Ready
Ring Buffer >100k events/sec throughput ✅ Production Ready
Event Ingestor <1µs per event processing ✅ Production Ready
State Reconstruction <10ms for typical GenServer ✅ Production Ready
AST Transformation <100ms for medium modules ✅ Production Ready
AI Analysis <30s for project analysis ✅ Functional
Cinema Demo ~1 minute complete showcase ✅ Fully Working

Memory Usage

🗺️ Development Roadmap

✅ Phase 1: Foundation Complete (May 2025)

Major Achievements

Phase 2: Web Interface & Enhanced Features (Q2 2025)

Immediate Priorities

Enhanced Features

Phase 3: Advanced Features (Q2-Q3 2025)

🤝 Contributing

We welcome contributions! ElixirScope is built with a solid foundation and clear architecture.

Current Contribution Opportunities

  1. Web Interface - Build the Phoenix-based Cinema Debugger web UI
  2. Visual Debugging - Create interactive time-travel debugging interface
  3. AI Enhancement - Improve code analysis and pattern recognition
  4. Performance Optimization - Enhance event processing and storage
  5. Documentation - Improve guides and examples
  6. Testing - Add property-based and chaos testing

Getting Started with Development

  1. Fork the repository
  2. Set up development environment: 
    mix deps.get
mix test  # Ensure all tests pass (723 tests, excludes live API tests)
  3. Try the Cinema Demo: 
    cd test_apps/cinema_demo
./run_showcase.sh
  4. Create a feature branch
  5. Add comprehensive tests for new functionality
  6. Submit a pull request

Development Guidelines

📄 License

ElixirScope is released under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

ElixirScope builds on the excellent foundation of the Elixir and OTP ecosystem. Special thanks to:

📞 Support & Community

ElixirScope: Transforming Elixir development through intelligent instrumentation and AI-powered analysis. The future of debugging is here - and it's working! 🎬✨

🚀 Try the Cinema Demo Now!