|
1 | | -# AI Agent Guide for ContribAI |
| 1 | +# Copilot instructions |
2 | 2 |
|
3 | | -> This document is designed for AI assistants (GitHub Copilot, Claude, Cursor, Coderabbit, etc.) |
4 | | -> scanning this repository. It provides structured context to help AI understand the codebase. |
| 3 | +Read and follow [`AGENTS.md`](../AGENTS.md) before changing this repository. |
5 | 4 |
|
6 | | -## What This Project Is |
| 5 | +The maintained implementation is Rust in `crates/contribai-rs`; `python/` is legacy reference |
| 6 | +code. Preserve ContribAI's core invariant: analysis is the default, and every external write needs |
| 7 | +explicit operator intent, repository consent, scoped admission, evidence, and human review. Never |
| 8 | +add a CLA-signing flow or a publication bypass. |
7 | 9 |
|
8 | | -ContribAI is an **autonomous AI agent** that contributes to open source projects on GitHub. |
9 | | -It discovers repos, analyzes code, generates fixes, and submits pull requests — all without human intervention. |
10 | | - |
11 | | -**It is NOT** a library/SDK, web app, or CLI tool intended for end-user consumption. |
12 | | -It is itself an AI agent that operates on other GitHub repositories. |
13 | | - |
14 | | -## Tech Stack |
15 | | - |
16 | | -| Layer | Technology | |
17 | | -|-------|-----------| |
18 | | -| Language | Python 3.11+ | |
19 | | -| Async | asyncio, aiohttp | |
20 | | -| HTTP | httpx (async) | |
21 | | -| Database | SQLite (aiosqlite) | |
22 | | -| LLM | Google Gemini (primary), OpenAI, Anthropic, Ollama, Vertex AI | |
23 | | -| GitHub | REST API v3 (via httpx) | |
24 | | -| Web | FastAPI + uvicorn | |
25 | | -| CLI | Typer + Rich | |
26 | | -| Tests | pytest (333 tests) | |
27 | | -| Lint | ruff | |
28 | | - |
29 | | -## Architecture (v2.4.1) |
30 | | - |
31 | | -### Core Pipeline |
32 | | -``` |
33 | | -Discovery → Middleware Chain → Analysis → Generation → PR → CI Monitor |
34 | | -``` |
35 | | - |
36 | | -### Key Patterns |
37 | | -1. **Middleware Chain** — 5 ordered middlewares (`contribai/core/middleware.py`) |
38 | | -2. **Progressive Skills** — 17 analysis skills loaded on-demand (`contribai/analysis/skills.py`) |
39 | | -3. **Sub-Agent Registry** — 4 agents with parallel execution (`contribai/agents/registry.py`) |
40 | | -4. **Tool Protocol** — MCP-inspired tool interface (`contribai/tools/protocol.py`) |
41 | | -5. **Outcome Learning** — Tracks PR outcomes to learn per-repo preferences (`contribai/orchestrator/memory.py`) |
42 | | -6. **Context Summarization** — Compresses analysis results for LLM context (`contribai/analysis/analyzer.py`) |
43 | | - |
44 | | -### Module Dependency Graph |
45 | | -``` |
46 | | -cli/main.py |
47 | | - └── orchestrator/pipeline.py (entry point) |
48 | | - ├── core/config.py (configuration) |
49 | | - ├── core/middleware.py (pipeline middlewares) |
50 | | - ├── github/client.py (HTTP API) |
51 | | - ├── github/discovery.py (repo search) |
52 | | - ├── analysis/analyzer.py (7 analyzers) |
53 | | - │ └── analysis/skills.py (progressive loading) |
54 | | - ├── generator/engine.py (code generation) |
55 | | - │ └── generator/scorer.py (quality scoring) |
56 | | - ├── pr/manager.py (PR lifecycle) |
57 | | - ├── pr/patrol.py (review monitoring) |
58 | | - ├── issues/solver.py (issue solving) |
59 | | - ├── orchestrator/memory.py (SQLite persistence) |
60 | | - ├── agents/registry.py (sub-agent orchestration) |
61 | | - └── tools/protocol.py (tool interface) |
62 | | -``` |
63 | | - |
64 | | -## Code Conventions |
65 | | - |
66 | | -| Convention | Standard | |
67 | | -|-----------|---------| |
68 | | -| Naming | `snake_case` for functions/variables, `PascalCase` for classes | |
69 | | -| Docstrings | Google style with Args/Returns/Raises | |
70 | | -| Async | All I/O operations are `async/await` | |
71 | | -| Error handling | `try/except` with logging, no bare `except` | |
72 | | -| Imports | Absolute imports, `from __future__ import annotations` | |
73 | | -| Type hints | Full type hints, `str | None` style unions | |
74 | | -| Line length | 100 chars (ruff) | |
75 | | -| Formatting | ruff format | |
76 | | - |
77 | | -## Common Patterns |
78 | | - |
79 | | -### LLM Calls |
80 | | -```python |
81 | | -# All LLM calls go through LLMProvider.complete() |
82 | | -response = await self._llm.complete(prompt, system_prompt=system) |
83 | | -``` |
84 | | - |
85 | | -### GitHub API Calls |
86 | | -```python |
87 | | -# All GitHub API calls go through GitHubClient |
88 | | -content = await self._github.get_file_content(owner, repo, path) |
89 | | -await self._github.create_or_update_file(owner, repo, path, content, message, signoff=signoff) |
90 | | -``` |
91 | | - |
92 | | -### Configuration |
93 | | -```python |
94 | | -# All config through Pydantic-like dataclasses in core/config.py |
95 | | -config = ContribAIConfig.from_yaml("config.yaml") |
96 | | -config.github.token # str |
97 | | -config.llm.provider # str |
98 | | -config.analysis.enabled_analyzers # list[str] |
99 | | -``` |
100 | | - |
101 | | -### Memory/Persistence |
102 | | -```python |
103 | | -# SQLite via aiosqlite |
104 | | -memory = Memory("~/.contribai/memory.db") |
105 | | -await memory.init() |
106 | | -await memory.record_outcome(repo, pr_number, url, type, "merged") |
107 | | -prefs = await memory.get_repo_preferences(repo) |
108 | | -``` |
109 | | - |
110 | | -## File Organization Rules |
111 | | - |
112 | | -- **Code files only**: ContribAI only modifies `.py`, `.js`, `.ts`, `.go`, `.rs` etc. |
113 | | -- **Never modify**: `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `.github/FUNDING.yml` |
114 | | -- **Skip extensions**: `.md`, `.yaml`, `.json`, `.toml`, `.cfg`, `.ini` |
115 | | -- **Protected meta files**: Any governance/meta files are off-limits |
116 | | - |
117 | | -## Testing |
| 10 | +Before submitting changes, run: |
118 | 11 |
|
119 | 12 | ```bash |
120 | | -pytest tests/ -v # 333 tests |
121 | | -pytest tests/ -v --cov=contribai # With coverage (threshold: 50%) |
122 | | -``` |
123 | | - |
124 | | -Test structure: |
125 | | -``` |
126 | | -tests/ |
127 | | -├── unit/ # Unit tests for each module |
128 | | -│ ├── test_analyzer.py |
129 | | -│ ├── test_config.py |
130 | | -│ ├── test_pipeline_v2.py |
131 | | -│ ├── test_github_client.py |
132 | | -│ ├── test_patrol.py |
133 | | -│ └── ... |
134 | | -└── conftest.py # Shared fixtures |
| 13 | +cargo fmt --all -- --check |
| 14 | +cargo clippy --workspace --all-targets --locked -- -D warnings |
| 15 | +cargo test --workspace --locked |
135 | 16 | ``` |
136 | | - |
137 | | -## Environment Variables |
138 | | - |
139 | | -| Variable | Required | Purpose | |
140 | | -|----------|----------|---------| |
141 | | -| `GITHUB_TOKEN` | Yes | GitHub API authentication | |
142 | | -| `GEMINI_API_KEY` | Yes* | Google Gemini LLM | |
143 | | -| `OPENAI_API_KEY` | Alt | OpenAI LLM (alternative) | |
144 | | -| `ANTHROPIC_API_KEY` | Alt | Anthropic LLM (alternative) | |
145 | | -| `GOOGLE_CLOUD_PROJECT` | Opt | Vertex AI project | |
146 | | - |
147 | | -## Known Limitations |
148 | | - |
149 | | -1. No sandbox execution — ContribAI generates code but doesn't run it |
150 | | -2. Single-repo PRs only — no cross-repo changes |
151 | | -3. No interactive mode — fully autonomous |
152 | | -4. Rate limited by GitHub API (5000 req/hour for authenticated users) |
153 | | -5. Context window limited by LLM provider (varies by model) |
0 commit comments