README.md

Select File:
# 🧠 Autogentic

[![Tests](https://img.shields.io/badge/tests-64%20passing-brightgreen)](https://github.com/c-u-l8er/autogentic)
[![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/c-u-l8er/autogentic)
[![Elixir](https://img.shields.io/badge/elixir-~>%201.15-purple)](https://elixir-lang.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)

**Revolutionary effects-first architecture that makes traditional multi-agent systems look primitive.**

Autogentic v2.0 is a sophisticated multi-agent system built with Elixir that enables the creation of intelligent, reasoning-capable agents that can coordinate complex workflows, learn from experience, and adapt their behavior over time.

## ✨ Key Features

### 🎭 **Advanced Effects System**
- **20+ Built-in Effects**: From simple logging to complex multi-agent coordination
- **Composable Workflows**: Sequence, parallel, and race execution patterns
- **Error Handling**: Retry, compensation, circuit breaker, and timeout patterns
- **Context Management**: Sophisticated state management across effect chains

### 🧠 **AI-Powered Reasoning Engine**
- **Multi-Dimensional Analysis**: Assessment, evaluation, synthesis, and prediction
- **Confidence Scoring**: Each reasoning step includes confidence metrics
- **Knowledge Base Integration**: Query and learn from accumulated knowledge
- **Pattern Recognition**: Automatically identify and store successful reasoning patterns

### 🤖 **Intelligent Agent Framework**
- **Declarative Agent Definition**: Define agents with simple, expressive DSL
- **State Machine Architecture**: Robust state transitions with effect-driven behavior
- **Multi-Agent Coordination**: Built-in communication and collaboration primitives
- **Adaptive Behavior**: Agents learn and evolve their strategies over time

### 🎓 **Continuous Learning System**
- **Cross-Agent Knowledge Sharing**: Agents share insights and learned patterns
- **Behavioral Adaptation**: Automatic strategy refinement based on outcomes
- **Performance Optimization**: Self-improving system efficiency over time
- **Reasoning Pattern Storage**: Accumulate and reuse successful decision-making approaches

### 🏗️ **Enterprise-Grade Reliability**
- **Circuit Breakers**: Prevent cascading failures in distributed systems
- **Compensation Patterns**: Automatic rollback and recovery mechanisms
- **Retry Logic**: Configurable retry strategies with exponential backoff
- **Graceful Degradation**: System continues operating even with partial failures

## 🚀 Quick Start

### Prerequisites

- Elixir 1.15+ 
- Erlang/OTP 24+

### Installation

```bash
git clone https://github.com/c-u-l8er/autogentic.git
cd autogentic
mix deps.get
```

### Run Your First Agent

```elixir
# Start the Autogentic system
iex -S mix

# Create a simple agent
defmodule MyFirstAgent do
  use Autogentic.Agent, name: :my_agent

  agent :my_agent do
    capability [:greeting]
    initial_state :ready
  end

  state :ready do
    # Agent is ready for interactions
  end

  transition from: :ready, to: :ready, when_receives: :hello do
    sequence do
      log(:info, "Hello from Autogentic!")
      put_data(:greetings_count, 1)
      emit_event(:greeting_sent, %{agent: :my_agent})
    end
  end
end

# Start and interact with your agent
{:ok, pid} = MyFirstAgent.start_link()
GenStateMachine.cast(pid, :hello)
```

## 📚 Examples

We've created comprehensive examples that demonstrate Autogentic's capabilities across different use cases:

### 🟢 Basic Examples
- **[Hello Agent](examples/basic/hello_agent.exs)** - Your first Autogentic agent
- **[Effects Showcase](examples/basic/effects_showcase.exs)** - Comprehensive effects demonstration
- **[Learning Agent](examples/basic/learning_agent.exs)** - Adaptive behavior and continuous learning

### 🤝 Multi-Agent Coordination
- **[Deployment Team](examples/coordination/deployment_team.exs)** - Coordinated software deployment workflow
- Multiple agents (Dev, QA, Ops) working together
- Real-time communication and status synchronization
- Complex workflow orchestration

### 🧠 Advanced Reasoning
- **[Decision Maker](examples/reasoning/decision_maker.exs)** - Sophisticated reasoning workflows
- Multi-step analysis with confidence scoring
- Knowledge base querying and pattern recognition
- Context-aware decision making

### 🏭 Real-World Applications
- **[Data Pipeline](examples/real_world/data_pipeline.exs)** - Enterprise data processing pipeline
- Data ingestion, transformation, and ML analysis
- Quality monitoring and anomaly detection
- Intelligent pipeline optimization

### Running Examples

```bash
# Recommended: Use the example runner (ensures system is properly initialized)
mix run run_example.exs examples/basic/hello_agent.exs
mix run run_example.exs examples/coordination/deployment_team.exs

# Alternative: Run in interactive mode
iex -S mix
iex> c "examples/basic/hello_agent.exs"
iex> HelloAgentExample.run()

# List all available examples
mix run run_example.exs
```

## 🎯 Core Concepts

### Effects-First Architecture

Autogentic is built around the concept of **effects** - declarative descriptions of what should happen:

```elixir
# Simple effect
{:log, :info, "Hello World"}

# Complex workflow
{:sequence, [
  {:put_data, :start_time, DateTime.utc_now()},
  {:parallel, [
    {:delay, 100},
    {:log, :info, "Processing..."},
    {:emit_event, :started, %{}}
  ]},
  {:put_data, :completed, true}
]}
```

### Agent Coordination

Agents communicate through reasoning broadcasts and event emissions:

```elixir
# Agent A shares insights with Agent B
broadcast_reasoning("Analysis complete", [:agent_b])

# Agent B receives and processes the shared reasoning
behavior :process_shared_reasoning, triggers_on: [:reasoning_shared] do
  sequence do
    log(:info, "Received insight from peer agent")
    put_data(:external_insight_received, true)
    adapt_coordination_strategy(%{collaboration_level: :high})
  end
end
```

### Reasoning Integration

Every agent can perform sophisticated reasoning:

```elixir
# Start a reasoning session
{:ok, session_id} = Autogentic.start_reasoning("deployment_decision", context)

# Add reasoning steps
step = %{
  question: "Is the system ready for deployment?",
  analysis_type: :assessment,
  context_required: [:system_health, :test_results]
}

{:ok, processed_step} = Autogentic.Reasoning.Engine.add_reasoning_step(session_id, step)

# Get conclusion with confidence score
{:ok, conclusion} = Autogentic.Reasoning.Engine.conclude_reasoning_session(session_id)
```

## 🧪 Testing

Autogentic comes with a comprehensive test suite covering all major functionality:

```bash
# Run all tests
mix test

# Run with coverage
mix test --cover

# Run specific test categories
mix test test/autogentic/effects/
mix test test/autogentic/reasoning/
mix test test/autogentic/agent/
```

**Current Test Status**: 64 tests passing ✅

## 🏗️ Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                        Autogentic v2.0                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Agent Layer   │  │  Reasoning      │  │   Learning      │ │
│  │                 │  │   Engine        │  │ Coordinator     │ │
│  │ • State Machine │  │ • Multi-Step    │  │ • Pattern       │ │
│  │ • Behaviors     │  │   Analysis      │  │   Storage       │ │
│  │ • Coordination  │  │ • Knowledge     │  │ • Adaptation    │ │
│  │ • Effects       │  │   Base          │  │ • Sharing       │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│                     Effects Engine                              │
│  • Sequence/Parallel/Race Execution • Error Handling           │
│  • Retry/Compensation/Circuit Breaker • Context Management     │
├─────────────────────────────────────────────────────────────────┤
│                   GenStateMachine + OTP                        │
│            Erlang/OTP • Actor Model • Supervision              │
└─────────────────────────────────────────────────────────────────┘
```

## 🔧 Configuration

Configure Autogentic in your `config/config.exs`:

```elixir
config :autogentic,
  # Effects Engine settings
  effects_timeout: 30_000,
  max_parallel_effects: 100,
  
  # Reasoning Engine settings
  max_reasoning_steps: 20,
  confidence_threshold: 0.6,
  
  # Learning settings
  pattern_storage_enabled: true,
  cross_agent_learning: true,
  
  # Logging
  log_level: :info
```

## 🗺️ Roadmap

### Phase 1: Production Readiness ⏳
- [ ] Real LLM Integration (OpenAI, Anthropic, Claude)
- [ ] Persistent State Management (PostgreSQL)
- [ ] Enhanced Web Interface
- [ ] Performance Optimization

### Phase 2: Advanced AI Capabilities ⏳
- [ ] Multi-Modal Reasoning (Text, Image, Code)
- [ ] Advanced Learning Algorithms
- [ ] Distributed Agent Networks
- [ ] Real-Time Collaboration Tools

### Phase 3: Enterprise Features ⏳
- [ ] Security & Authentication
- [ ] Multi-Tenant Support
- [ ] API Gateway Integration
- [ ] Monitoring & Analytics Dashboard

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/c-u-l8er/autogentic.git
cd autogentic

# Install dependencies
mix deps.get

# Run tests
mix test

# Run examples
mix run examples/basic/hello_agent.exs
```

## 📖 Documentation

- **[API Documentation](https://hexdocs.pm/autogentic)** - Complete API reference
- **[Agent Guide](docs/agent_guide.md)** - Creating and managing agents
- **[Effects Reference](docs/effects_reference.md)** - Complete effects catalog
- **[Reasoning Guide](docs/reasoning_guide.md)** - Advanced reasoning techniques
- **[Deployment Guide](docs/deployment.md)** - Production deployment

## 💬 Community

- **Discord**: [Join our community](https://discord.gg/autogentic)
- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/c-u-l8er/autogentic/discussions)
- **Blog**: [Read about Autogentic developments](https://blog.autogentic.ai)

## 📄 License

This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with the powerful [Elixir](https://elixir-lang.org/) programming language
- Leveraging [OTP](https://www.erlang.org/doc/design_principles/des_princ.html) for rock-solid concurrency
- Inspired by cutting-edge research in multi-agent systems and AI reasoning

---

**Ready to build the future of intelligent systems?** 🚀

```bash
git clone https://github.com/c-u-l8er/autogentic.git
cd autogentic
mix deps.get
iex -S mix
```

*Welcome to Autogentic v2.0 - where agents think, learn, and collaborate.*