# aipartnerupflow Documentation

Welcome to the aipartnerupflow documentation! This is your complete guide to building task orchestration workflows.

## Problems We Solve

You might be struggling with these common challenges:

- **Managing Complex Task Dependencies**: Manually tracking which tasks depend on others, ensuring proper execution order, and handling failures across complex workflows becomes a nightmare. You end up writing custom coordination code, dealing with race conditions, and spending weeks debugging dependency issues.

- **Integrating Multiple Execution Methods**: You need to call HTTP APIs, execute SSH commands, run Docker containers, communicate via gRPC, and coordinate AI agents—but each requires different libraries, error handling, and integration patterns. Managing multiple orchestration systems becomes overwhelming.

- **Combining Traditional Tasks with AI Agents**: You want to add AI capabilities to existing workflows, but most solutions force you to choose: either traditional task execution OR AI agents. You're stuck with all-or-nothing decisions, requiring complete rewrites to introduce AI gradually.

- **State Persistence and Recovery**: When workflows fail or get interrupted, you lose progress. Implementing retry logic, checkpointing, and state recovery requires significant custom development. You spend more time building infrastructure than solving business problems.

- **Real-time Monitoring**: You need to show progress to users, but building real-time monitoring with polling, WebSocket connections, or custom streaming solutions takes weeks. Your users wait without feedback, and you struggle to debug long-running workflows.

## Why aipartnerupflow?

Here's what makes aipartnerupflow the right choice:

- **One Unified Interface for Everything**: Stop managing multiple orchestration systems. One framework handles traditional tasks, HTTP/REST APIs, SSH commands, Docker containers, gRPC services, WebSocket communication, MCP tools, and AI agents—all through the same ExecutableTask interface.

- **Start Simple, Scale Up Gradually**: Begin with a lightweight, dependency-free core that handles traditional task orchestration. Add AI capabilities, A2A server, CLI tools, or PostgreSQL storage only when you need them. Unlike frameworks that force you to install everything upfront, aipartnerupflow lets you start minimal and grow incrementally.

- **Language-Agnostic Protocol**: Built on the AI Partner Up Flow Protocol, ensuring interoperability across Python, Go, Rust, JavaScript, and more. Different language implementations work together seamlessly.

- **Production-Ready from Day One**: Built-in storage (DuckDB or PostgreSQL), real-time streaming, automatic retries, state persistence, and comprehensive monitoring—all included. No need to build these from scratch.

- **Extensive Executor Ecosystem**: Choose from HTTP/REST APIs (with authentication), SSH remote execution, Docker containers, gRPC services, WebSocket communication, MCP integration, and LLM-based task tree generation.

## What Happens When You Use aipartnerupflow?

- **You Build Workflows Faster**: Before: Weeks of custom coordination code. After: Define task trees with dependencies in days, not weeks. The framework handles coordination, error recovery, and state management automatically.

- **You Integrate Everything Easily**: Before: Multiple orchestration systems for different execution methods. After: One unified interface for all execution methods. Mix HTTP calls, SSH commands, Docker containers, and AI agents in a single workflow seamlessly.

- **You Add AI Gradually**: Before: All-or-nothing decisions requiring complete rewrites. After: Start with traditional task orchestration, then add AI agents incrementally when ready. No rewrites needed.

- **You Monitor in Real-Time**: Before: Weeks building custom polling or streaming solutions. After: Built-in real-time streaming via A2A Protocol. Monitor progress, task status, and intermediate results instantly.

- **You Recover from Failures Automatically**: Before: Manual recovery logic and lost progress. After: Automatic retries with exponential backoff, state persistence, and workflow resumption from checkpoints.

- **You Scale with Confidence**: Before: Worrying about resource usage and dependency management at scale. After: Production-ready from day one. Handle hundreds of concurrent workflows with confidence.

## 🚀 New to aipartnerupflow?

**Start here if you're new:**

1. **[Getting Started](getting-started/index.md)** - Overview and learning paths
2. **[Quick Start Guide](getting-started/quick-start.md)** - Get running in 10 minutes
3. **[First Steps Tutorial](getting-started/tutorials/tutorial-01-first-steps.md)** - Complete beginner tutorial
4. **[Core Concepts](getting-started/concepts.md)** - Understand the fundamentals

**Quick Installation:**
```bash
pip install aipartnerupflow
```

## 📚 Documentation Structure

### For Beginners

**Start Here:**
- **[Getting Started](getting-started/index.md)** - Your starting point
- **[Quick Start](getting-started/quick-start.md)** - 10-minute quick start
- **[First Steps Tutorial](getting-started/tutorials/tutorial-01-first-steps.md)** - Complete beginner tutorial
- **[Core Concepts](getting-started/concepts.md)** - Learn the basics

**Learn by Doing:**
- **[Basic Examples](examples/basic_task.md)** - Copy-paste ready examples
- **[Installation Guide](getting-started/installation.md)** - Installation options

### For Developers

**Guides:**
- **[Task Orchestration](guides/task-orchestration.md)** - Master task trees, dependencies, and priorities
- **[Custom Tasks](guides/custom-tasks.md)** - Create your own executors
- **[Best Practices](guides/best-practices.md)** - Design patterns and optimization
- **[FAQ](guides/faq.md)** - Common questions and troubleshooting

**API Reference:**
- **[Python API](api/python.md)** - Complete Python API reference
- **[Quick Reference](api/quick-reference.md)** - Cheat sheet with common snippets
- **[HTTP API](api/http.md)** - A2A Protocol Server HTTP API

**Examples:**
- **[Basic Examples](examples/basic_task.md)** - Common patterns and use cases
- **[Task Tree Examples](examples/task-tree.md)** - Complex workflow examples
- **[Real-World Examples](examples/real-world.md)** - Production-ready use cases

### For Contributors

**Development:**
- **[Development Setup](development/setup.md)** - Set up your development environment
- **[Contributing](development/contributing.md)** - How to contribute
- **[Extending](development/extending.md)** - Extend the framework
- **[Design Documents](development/design/)** - Feature design documents

**Architecture:**
- **[Architecture Overview](architecture/overview.md)** - System design and principles
- **[Architecture Diagrams](architecture/diagrams.md)** - Visual diagrams (sequence, flow, state diagrams)
- **[Directory Structure](architecture/directory-structure.md)** - Code organization
- **[Extension Registry](architecture/extension-registry-design.md)** - Extension system design
- **[Naming Conventions](architecture/naming-convention.md)** - Code style guide
- **[Configuration](architecture/configuration.md)** - Configuration options

## 🎯 Quick Navigation

### By Task

**I want to...**

- **Get started quickly** → [Quick Start](getting-started/quick-start.md)
- **Understand concepts** → [Core Concepts](getting-started/concepts.md)
- **Create a custom executor** → [Custom Tasks Guide](guides/custom-tasks.md)
- **Build complex workflows** → [Task Orchestration Guide](guides/task-orchestration.md)
- **See examples** → [Basic Examples](examples/basic_task.md)
- **Find API reference** → [Python API](api/python.md) or [Quick Reference](api/quick-reference.md)
- **Troubleshoot issues** → [FAQ](guides/faq.md)
- **Learn best practices** → [Best Practices](guides/best-practices.md)
- **Set up development** → [Development Setup](development/setup.md)
- **Understand architecture** → [Architecture Overview](architecture/overview.md)

### By Role

**I am a...**

- **New User** → Start with [Getting Started](getting-started/index.md)
- **Developer** → Check [Guides](guides/) and [API Reference](api/)
- **Contributor** → See [Development](development/) section
- **Architect** → Review [Architecture](architecture/) documentation

## 📖 Documentation Sections

### Getting Started
Essential guides for new users:
- **[Getting Started Index](getting-started/index.md)** - Overview and learning paths
- **[Quick Start](getting-started/quick-start.md)** - Get running in 10 minutes
- **[Installation](getting-started/installation.md)** - Installation options
- **[Core Concepts](getting-started/concepts.md)** - Fundamental concepts
- **[Examples](getting-started/examples.md)** - Quick examples

### Tutorials
Step-by-step tutorials:
- **[Tutorial 1: First Steps](getting-started/tutorials/tutorial-01-first-steps.md)** - Complete beginner tutorial
- **[Tutorial 2: Task Trees](getting-started/tutorials/tutorial-02-task-trees.md)** - Building task trees
- **[Tutorial 3: Dependencies](getting-started/tutorials/tutorial-03-dependencies.md)** - Working with dependencies

### Guides
Comprehensive guides for developers:
- **[Task Orchestration](guides/task-orchestration.md)** - Task trees, dependencies, priorities
- **[Custom Tasks](guides/custom-tasks.md)** - Creating custom executors
- **[Best Practices](guides/best-practices.md)** - Design patterns and optimization
- **[FAQ](guides/faq.md)** - Common questions and troubleshooting
- **[CLI](guides/cli.md)** - Command-line interface
- **[API Server](guides/api-server.md)** - API server setup

### Examples
Practical, runnable examples:
- **[Basic Examples](examples/basic_task.md)** - Common patterns and use cases
- **[Task Tree Examples](examples/task-tree.md)** - Complex workflows
- **[Real-World Examples](examples/real-world.md)** - Production-ready use cases

### API Reference
Complete API documentation:
- **[Python API](api/python.md)** - Core Python library API
- **[Quick Reference](api/quick-reference.md)** - Cheat sheet
- **[HTTP API](api/http.md)** - A2A Protocol Server API

### Architecture
System design and structure:
- **[Architecture Overview](architecture/overview.md)** - System design
- **[Architecture Diagrams](architecture/diagrams.md)** - Visual diagrams (sequence, flow, state diagrams)
- **[Directory Structure](architecture/directory-structure.md)** - Code organization
- **[Extension Registry](architecture/extension-registry-design.md)** - Extension system
- **[Naming Conventions](architecture/naming-convention.md)** - Code style
- **[Configuration](architecture/configuration.md)** - Configuration options

### Development
For contributors:
- **[Development Setup](development/setup.md)** - Development environment
- **[Contributing](development/contributing.md)** - Contribution guidelines
- **[Extending](development/extending.md)** - Extend the framework
- **[Design Documents](development/design/)** - Feature designs

## 🔗 External Resources

- **Main README**: [../README.md](../README.md) - Project overview
- **GitHub Repository**: [aipartnerup/aipartnerupflow](https://github.com/aipartnerup/aipartnerupflow)
- **Issues**: [GitHub Issues](https://github.com/aipartnerup/aipartnerupflow/issues)
- **Discussions**: [GitHub Discussions](https://github.com/aipartnerup/aipartnerupflow/discussions)

## 💡 Learning Path

### Path 1: Quick Start (15 minutes)
1. [Quick Start](getting-started/quick-start.md) - Get running
2. [Basic Examples](examples/basic_task.md) - Try examples
3. [Core Concepts](getting-started/concepts.md) - Understand basics

### Path 2: Complete Beginner (1-2 hours)
1. [Getting Started Index](getting-started/index.md) - Overview
2. [First Steps Tutorial](getting-started/tutorials/tutorial-01-first-steps.md) - Complete tutorial
3. [Task Trees Tutorial](getting-started/tutorials/tutorial-02-task-trees.md) - Build task trees
4. [Dependencies Tutorial](getting-started/tutorials/tutorial-03-dependencies.md) - Master dependencies
5. [Core Concepts](getting-started/concepts.md) - Deep dive
6. [Basic Examples](examples/basic_task.md) - Practice

### Path 3: Professional Developer (2-4 hours)
1. [Quick Start](getting-started/quick-start.md) - Quick refresher
2. [Task Orchestration](guides/task-orchestration.md) - Master orchestration
3. [Custom Tasks](guides/custom-tasks.md) - Create executors
4. [Best Practices](guides/best-practices.md) - Learn patterns
5. [API Reference](api/python.md) - Complete reference

### Path 4: Contributor (4+ hours)
1. [Development Setup](development/setup.md) - Set up environment
2. [Architecture Overview](architecture/overview.md) - Understand design
3. [Contributing](development/contributing.md) - Learn process
4. [Extending](development/extending.md) - Extend framework

## 🎓 Recommended Reading Order

**For New Users:**
1. [Getting Started Index](getting-started/index.md)
2. [Quick Start](getting-started/quick-start.md)
3. [First Steps Tutorial](getting-started/tutorials/tutorial-01-first-steps.md)
4. [Core Concepts](getting-started/concepts.md)
5. [Basic Examples](examples/basic_task.md)

**For Developers:**
1. [Quick Start](getting-started/quick-start.md) (if new)
2. [Task Orchestration](guides/task-orchestration.md)
3. [Custom Tasks](guides/custom-tasks.md)
4. [Best Practices](guides/best-practices.md)
5. [API Reference](api/python.md)

**For Contributors:**
1. [Development Setup](development/setup.md)
2. [Architecture Overview](architecture/overview.md)
3. [Architecture Diagrams](architecture/diagrams.md)
4. [Contributing](development/contributing.md)
5. [Extension Registry Design](architecture/extension-registry-design.md)

## 📝 Documentation Updates

This documentation is actively maintained. If you find issues or have suggestions:
- [Report Issues](https://github.com/aipartnerup/aipartnerupflow/issues)
- [Start Discussion](https://github.com/aipartnerup/aipartnerupflow/discussions)
- [Contribute](development/contributing.md)

---

**Ready to start?** → [Getting Started →](getting-started/index.md) or [Quick Start →](getting-started/quick-start.md)
