Metadata-Version: 2.4
Name: cicaddy
Version: 0.10.0
Summary: Platform-agnostic pipeline AI agent with MCP tool integration and multi-step execution engine
Author: Wayne Sun
License: Apache-2.0
Project-URL: Homepage, https://github.com/cicaddy/cicaddy
Project-URL: Repository, https://github.com/cicaddy/cicaddy.git
Project-URL: Issues, https://github.com/cicaddy/cicaddy/issues
Keywords: ai,agent,mcp,pipeline,workflow,code-review,automation,ci-cd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.0
Requires-Dist: slack-sdk>=3.33.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: jinja2>=3.1.4
Requires-Dist: structlog>=24.5.0
Requires-Dist: mcp>=1.13.1
Requires-Dist: anthropic>=0.21.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: google-api-python-client>=2.108.0
Requires-Dist: google-auth-httplib2>=0.2.0
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: protobuf>=5.26.0
Requires-Dist: openai>=1.102.0
Requires-Dist: fire>=0.7.0
Requires-Dist: websockets>=13.0
Requires-Dist: typing-extensions>=4.12.0; python_version < "3.12"
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: dspy-ai>=2.4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: aioresponses>=0.7.8; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: enterprise
Requires-Dist: opentelemetry-api>=1.27.0; extra == "enterprise"
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "enterprise"
Requires-Dist: opentelemetry-exporter-otlp>=1.27.0; extra == "enterprise"
Requires-Dist: opentelemetry-instrumentation>=0.48b0; extra == "enterprise"
Requires-Dist: redis>=5.0.0; extra == "enterprise"
Requires-Dist: psutil>=6.0.0; extra == "enterprise"
Provides-Extra: test
Requires-Dist: pytest>=8.4.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.14.0; extra == "test"
Requires-Dist: aioresponses>=0.7.8; extra == "test"
Provides-Extra: security
Requires-Dist: llm-guard>=0.3.0; extra == "security"
Provides-Extra: vertex
Requires-Dist: anthropic[vertex]>=0.21.0; extra == "vertex"
Provides-Extra: graph
Requires-Dist: code-review-graph>=1.2.0; extra == "graph"
Dynamic: license-file

# cicaddy

Platform-agnostic AI agent for running AI workflows in CI pipelines, with MCP tool integration and multi-step execution engine.

## Features

- **Multi-provider AI**: Gemini, OpenAI, Claude (direct API and Vertex AI)
- **Sub-agent delegation**: AI-powered triage with parallel specialized sub-agents
- **MCP integration**: Connect to any MCP-compatible tool server
- **Multi-step execution**: Token-aware execution engine with recovery
- **YAML task definitions**: DSPy-based task configuration
- **Notifications**: Slack and email notification support
- **HTML reports**: Customizable analysis report generation
- **Extensible agents**: Registry-based agent factory for custom agents

## Installation

```bash
pip install cicaddy

# With Vertex AI Claude support
pip install 'cicaddy[vertex]'
```

## Quick Start

```bash
# Run with environment file
cicaddy run --env-file .env

# Run with CLI arguments
cicaddy run --ai-provider gemini --agent-type task --log-level DEBUG

# Show configuration
cicaddy config show --env-file .env

# Validate configuration
cicaddy validate --env-file .env
```

## Configuration

Configure via environment variables or `.env` file:

```env
# AI Provider (Gemini)
AI_PROVIDER=gemini
AI_MODEL=gemini-3-flash
GEMINI_API_KEY=your-key-here

# AI Provider (Claude via Vertex AI — uses Google Cloud ADC, no API key needed)
# AI_PROVIDER=anthropic-vertex
# AI_MODEL=claude-sonnet-4-6
# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project
# CLOUD_ML_REGION=us-east5

# Agent
AGENT_TYPE=task
TASK_TYPE=scheduled_analysis

# MCP Servers (JSON array)
MCP_SERVERS_CONFIG=[]

# Notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/...

# DSPy Task File (takes precedence over AI_TASK_PROMPT)
AI_TASK_FILE=tasks/dora_report.yaml
```

### DSPy Task Definition (YAML)

Instead of raw prompt strings (`AI_TASK_PROMPT`), define structured tasks in YAML with typed inputs, expected outputs, MCP tool constraints, and reasoning strategy. Set `AI_TASK_FILE` to your task file path.

See [`examples/dora_metrics_task.yaml`](examples/dora_metrics_task.yaml) for a complete DORA metrics analysis task using DevLake MCP, and [`examples/templates/report_template.html`](examples/templates/report_template.html) for the HTML report template.

Key schema fields:

| Field | Description |
|-------|-------------|
| `inputs[].env_var` | Resolve value from environment variable at load time |
| `inputs[].format` | `diff` or `code` for fenced rendering in prompt |
| `tools.servers` | Restrict to specific MCP servers |
| `tools.required_tools` | Tools the AI must use during execution |
| `tools.forbidden_tools` | Tools the AI must not use |
| `reasoning` | `chain_of_thought`, `react`, or `simple` |
| `output_format` | `markdown`, `html`, or `json` |
| `context` | Supports `{{VAR}}` placeholders resolved at load time |

## Sub-Agent Delegation (v0.8.0+)

Enable AI-powered sub-agent delegation with `DELEGATION_MODE=auto`. An AI triage step analyzes the context, selects specialized sub-agents (security, architecture, performance, etc.), runs them in parallel with sibling awareness (each agent knows what others cover), and aggregates results.

```env
# Add to your .env
DELEGATION_MODE=auto
MAX_SUB_AGENTS=3
```

```bash
cicaddy run --env-file .env
```

Built-in review agents: `security-reviewer`, `architecture-reviewer`, `api-reviewer`, `database-reviewer`, `ui-reviewer`, `devops-reviewer`, `performance-reviewer`, `general-reviewer`. Custom agents can be defined via YAML files in `.agents/delegation/`.

See [`docs/sub-agent-delegation.md`](docs/sub-agent-delegation.md) for full configuration, built-in agent details, custom agent YAML format, and tool filtering.
See [`examples/delegation/`](examples/delegation/) for example configurations.

## Extending with Platform Plugins

`cicaddy` discovers platform plugins automatically via Python `entry_points`. Plugins can register agents, CLI args, env vars, config sections, validators, and a settings loader — without modifying cicaddy itself.

**1. Define plugin callables** (`my_plugin/plugin.py`):

```python
def register_agents():
    from cicaddy.agent.factory import AgentFactory
    from my_plugin.agent import MergeRequestAgent, detect_agent_type

    AgentFactory.register("merge_request", MergeRequestAgent)
    AgentFactory.register_detector(detect_agent_type, priority=40)

def get_cli_args():
    from cicaddy.cli.arg_mapping import ArgMapping
    return [
        ArgMapping(cli_arg="--mr-iid", env_var="CI_MERGE_REQUEST_IID",
                   help_text="Merge request IID"),
    ]
```

**2. Register in `pyproject.toml`**:

```toml
[project.entry-points."cicaddy.agents"]
my_platform = "my_plugin.plugin:register_agents"

[project.entry-points."cicaddy.cli_args"]
my_platform = "my_plugin.plugin:get_cli_args"

[project.entry-points."cicaddy.settings_loader"]
my_platform = "my_plugin.config:load_settings"
```

**3. Install and run** — plugins are discovered automatically:

```bash
pip install cicaddy my-cicaddy-plugin
cicaddy run --env-file .env
```

Available plugin groups: `cicaddy.agents`, `cicaddy.cli_args`, `cicaddy.env_vars`, `cicaddy.config_sections`, `cicaddy.validators`, `cicaddy.settings_loader`.

### Official Plugins

| Plugin | Platform | Description |
|--------|----------|-------------|
| [cicaddy-gitlab](https://github.com/redhat-community-ai-tools/cicaddy-gitlab) | GitLab | AI-powered merge request reviews and branch analysis for GitLab CI |
| [cicaddy-action](https://github.com/redhat-community-ai-tools/cicaddy-action) | GitHub | GitHub Action for AI PR reviews and changelog generation |

## License

Apache-2.0
