Metadata-Version: 2.4
Name: polycoding
Version: 0.1.0
Summary: Coding agent that lives in your project management tool
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: alive-progress==3.3.0
Requires-Dist: celery>=5.4.0
Requires-Dist: click>=8.0.0
Requires-Dist: crewai-tools>=0.76.0
Requires-Dist: crewai[litellm]>=1.10.0b1
Requires-Dist: fastapi>=0.115.0
Requires-Dist: flower>=2.0.1
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-core>=1.2.19
Requires-Dist: ollama>=0.6.1
Requires-Dist: pathspec>=0.12.0
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pygithub>=2.8.1
Requires-Dist: pygls>=1.3.0
Requires-Dist: pyjwt[crypto]>=2.9.0
Requires-Dist: pyright>=1.1.408
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-socketio>=5.16.1
Requires-Dist: redis>=5.2.0
Requires-Dist: rich>=14.3.3
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: tqdm>=4.67.3
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-rust>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: ty>=0.0.21
Requires-Dist: typer>=0.23.1
Requires-Dist: uvicorn[standard]>=0.32.0
Description-Content-Type: text/markdown

# Polycode 🚀

Multi-agent software development automation using CrewAI with GitHub App integration for webhook-driven workflows.

## Overview

Polycode automates software development tasks using AI-powered multi-agent workflows built with CrewAI. It integrates as a GitHub App to provide seamless automation across multiple repositories.

**Key Features:**

- **Multi-agent workflows** with CrewAI framework
- **GitHub App integration** for multi-repo automation
- **Webhook-driven automation** triggered by labels
- **Push to external repos** via GitHub App tokens
- **Label-to-flow mapping** (e.g., `ralph` → `ralph_flow`)

### Available Workflows

- **Ralph Flow** (`ralph`): Fast iterative implementation with automated verification
- **Feature Development Flow** (`feature-dev`): Comprehensive feature implementation with planning, testing, and review

## Ralph Flow

The Ralph Flow is an iterative development workflow that implements changes with built-in verification loops. It's designed for fast, reliable code changes with automatic quality checks.

### How It Works

1. **Setup** - Initialize worktree and pick up the issue
2. **Plan** - Decompose the task into ordered user stories
3. **Ralph Loop** - Iterative implementation with verification:
   - Implement the current story
   - Run tests to verify changes
   - If tests fail, retry with error context (max 3 iterations)
   - If tests pass, commit the story and move to next
4. **Verify Build** - Final build and test verification
5. **Push & PR** - Push changes and create pull request

### Ralph Loop Control Flow

The loop uses a router-based mechanism with status outputs:

- **`retry`** → Continue loop with error context included
- **`story_done`** → Commit current story, proceed to next
- **`done`** → All stories complete, run final verification

Key safety features:

- **Per-Story Commits**: Each story is committed immediately upon completion
- **Safety Brake**: Maximum 3 iterations per story prevents runaway processes
- **Error Context**: Agent receives previous errors for smarter retries

### Tools Available to Ralph Agents

- **FileReadTool** - Read file contents
- **FileWriterTool** - Write/modify files
- **DirectoryReadTool** - Explore directory structure
- **ExecTool** - Execute shell commands (build, test, lint)
- **AgentsMDLoaderTool** - Load AGENTS.md context files

## Feature Development Flow

A comprehensive workflow for larger feature implementations:

1. **Plan** - Decompose task into ordered user stories
2. **Implement** - Implement each story with tests
3. **Push** - Push changes to repository
4. **Create PR** - Create pull request
5. **Review** - Code review with feedback

## Project Structure

```
polycode/
├── src/
│   ├── ralph/               # Ralph Loop workflow
│   │   ├── crews/
│   │   │   ├── plan_crew/   # Planning crew
│   │   │   └── ralph_crew/  # Implementation crew
│   │   └── __init__.py      # Ralph flow definition
│   ├── feature_dev/         # Feature development workflow
│   │   └── crews/
│   │       ├── plan_crew/
│   │       ├── implement_crew/
│   │       ├── verify_crew/
│   │       ├── test_crew/
│   │       └── review_crew/
│   ├── github_app/          # GitHub App integration
│   ├── project_manager/     # Project management utilities
│   ├── celery_tasks/        # Async task processing
│   ├── persistence/         # Database layer
│   ├── tools/               # Custom CrewAI tools
│   └── flowbase.py          # Base flow classes
├── tests/                   # Test files
└── pyproject.toml           # Project configuration
```

## Installation

### Prerequisites

- Python 3.13 or higher
- `uv` package manager

### Setup

```bash
# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your credentials
```

Required environment variables:

- `GITHUB_TOKEN` - GitHub personal access token
- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_HOST` / `REDIS_PORT` - Redis configuration
- `OPENAI_API_KEY` - OpenAI API key

## Usage

### Running Flows

```bash
# Run Ralph flow example
uv run ralph

# Run feature development example
uv run example
```

### GitHub App Integration

Polycode includes GitHub App support for webhook-driven automation:

1. **Create GitHub App** at <https://github.com/settings/apps/new>
2. **Configure permissions**: Issues, Projects, Contents, Pull requests (Read & Write)
3. **Set webhook URL** and secret
4. **Generate private key** and add to `.env`
5. **Install app** on target repositories
6. **Create label mappings** to trigger flows

### Label-to-Flow Mapping

```bash
# Map "ralph" label to ralph flow
curl -X POST http://localhost:8000/mappings \
  -H "Content-Type: application/json" \
  -d '{
    "installation_id": 12345,
    "label_name": "ralph",
    "flow_name": "ralph_flow"
  }'
```

## Development

### Commands

```bash
uv sync                   # Install dependencies
uv run ruff check .       # Lint
uv run ruff format .      # Format
uv run pytest             # Run tests
uv run pyright            # Type check
```

### Code Style

- Line length: 79 characters
- Use modern Python 3.10+ type annotations
- See `src/AGENTS.md` for complete guidelines

## Resources

- [CrewAI Documentation](https://docs.crewai.com/)
- [GitHub Apps Docs](https://docs.github.com/en/apps)

## License

MIT [LICENSE](./LICENSE)
