Metadata-Version: 2.4
Name: ai-code-checker
Version: 1.1.0
Summary: AI-powered code review agent using the Groq API
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: groq>=0.12.0
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: GitPython>=3.1.0
Requires-Dist: PyGithub>=2.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.27; extra == "server"
Requires-Dist: slowapi>=0.1.9; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# AI Code Checker

An intelligent, AST-aware CLI tool and CI action for automated code reviews powered by LLMs (Groq / Llama 3.3). Built for speed, precision, and seamless integration into developer workflows.

---

## Key Features

- **Git Diff Analysis:** Review only modified lines (`git diff` or specific commit refs) to save tokens and focus on actual changes.
- **AST-Aware Parsing & Chunking:** Uses `tree-sitter` to split large files logically along function and class boundaries without losing context.
- **Custom Team Guidelines:** Enforce project-specific standards via `.ai-review.toml` or `guidelines.md`.
- **CI Mode & Exit Codes:** Non-interactive plain text or JSON output with non-zero exit codes (`exit 1`) for high-severity findings to block PR merges.
- **Robust & Hardened:** Pydantic schema validation, path traversal defense, API timeouts, and automatic retry handling.

---

## Installation

### Local Installation

```bash
pip install ai-code-checker
```

> **Note:** The package name on PyPI is `ai-code-checker`; the executable is `ai-code-review`. Install from source if the package is not yet published:

```bash
git clone https://github.com/epicnellson/ai-code-reviewer.git
cd ai-code-reviewer
python -m pip install -e .
```

### Requirements

- Python 3.10 or newer
- Either a Groq API key (direct mode) or a hosted backend URL (client mode, no key needed)

### Configuration

Copy `.env.example` to `.env` and configure your access method:

```bash
cp .env.example .env
```

- **Direct mode:** set `GROQ_API_KEY` in your environment or `.env` (via `python-dotenv`). The GitHub Actions workflow instead uses the `GROQ_API_KEY` repository secret.
- **Client mode:** set `AI_REVIEW_API_URL` (and optionally `AI_REVIEW_API_TOKEN`) to point at a hosted backend. No Groq key required on the client.

---

## Hosted Backend (no API key for users)

Deploy the review server once; it holds the Groq API key and every CLI user talks to it.

### Deploy the server

```bash
pip install "ai-code-checker[server]"

# Server side: it needs the Groq key, not the clients.
GROQ_API_KEY=gsk_... AI_REVIEW_API_TOKEN=my-secret ai-review-server
```

- `ai-review-server` listens on `0.0.0.0:8000` by default (`AI_REVIEW_HOST` / `AI_REVIEW_PORT`).
- `AI_REVIEW_API_TOKEN` is optional; when set, clients must send it as a bearer token.
- `GET /health` for health checks. `POST /api/review/file` and `POST /api/review/diff` are the review endpoints.
- For production, run it behind a reverse proxy (nginx/Caddy) with TLS, and consider rate limiting.

### Deploy with Docker

Build and run the container locally:

```bash
docker build -t ai-code-review-server .
docker run -d -p 8000:8000 \
  -e GROQ_API_KEY=gsk_... \
  -e AI_REVIEW_API_TOKEN=my-secret \
  --name ai-review-server \
  ai-code-review-server
```

Verify the server is healthy:

```bash
curl http://localhost:8000/health
# → {"status":"ok","service":"ai-code-reviewer"}
```

To set a custom host or port, pass `AI_REVIEW_HOST` and `AI_REVIEW_PORT` environment variables:

```bash
docker run -d -p 9000:9000 \
  -e GROQ_API_KEY=gsk_... \
  -e AI_REVIEW_HOST=0.0.0.0 \
  -e AI_REVIEW_PORT=9000 \
  ai-code-review-server
```

### Use it as a client

Users just set the backend URL — no key:

```bash
export AI_REVIEW_API_URL=https://review.example.com
export AI_REVIEW_API_TOKEN=my-secret   # only if the server requires one

ai-code-review --file app.py
ai-code-review --diff HEAD~1 --ci
```

The client sends code and guidelines to the backend, which performs chunking and LLM review; exit codes and `--format json` behave exactly as in direct mode.

---

## Usage

### Review a Single File

```bash
ai-code-review --file path/to/your/file.py
```

For projects hosted under a different root directory, restrict path resolution:

```bash
ai-code-review --file src/app.py --base-dir ./src
```

### Review a Git Diff

Compare the working tree against a branch or commit ref:

```bash
# Against a remote branch (e.g. in CI)
ai-code-review --diff origin/main

# Against a commit ref
ai-code-review --diff HEAD~1

# Against local staged/unstaged changes (no value)
ai-code-review --diff
```

This analyzes only modified lines, saving tokens and focusing the review on actual changes.

### Adjust Chunking Budget

Very large files are split along function and class boundaries using `tree-sitter`. Tune the rough per-chunk token budget:

```bash
ai-code-review --file app.py --max-tokens 8000
```

---

## Custom Team Guidelines

Enforce project-specific standards by adding either a `.ai-review.toml` or a `guidelines.md` file in your repository root, or point to a file explicitly:

```bash
ai-code-review --file app.py --guidelines ./docs/code-standards.toml
```

`.ai-review.toml` supports a top-level string or list, or a `[review]` table:

```toml
guidelines = "Never use eval(). Every function needs a docstring."
```

```toml
guidelines = [
  "Never use eval().",
  "Every function needs a docstring.",
]
```

```toml
[review]
guidelines = "Prefer async over thread pools."
```

Guidelines are injected into every review prompt as authoritative rules and the reviewer flags violations.

---

## CI Mode & Exit Codes

Use `--ci` for non-interactive output:

```bash
ai-code-review --diff origin/main --ci --format text
```

- `--format text` prints human-readable output (default).
- `--format json` emits machine-readable structured results.
- The process exits with code `1` when high-severity bugs are found (in CI mode), so the step fails and blocks the PR merge. It exits `0` when the review is clean or only low/medium issues are found.

---

## GitHub Actions Integration

`.github/workflows/ai-review.yml` runs the review on every PR to `main`/`master`, comparing against the target branch and passing the `GROQ_API_KEY` secret:

```yaml
permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'
  - run: pip install -e .
  - run: ai-code-review --diff origin/${{ github.base_ref }} --ci --format text
    env:
      GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
```

Because the job exits non-zero on high-severity findings, a failing review automatically blocks PR merge checks. Add the job to your branch protection rules as a required status check for full enforcement.

---

## Release Automation

`.github/workflows/publish.yml` builds an sdist and wheel and publishes to PyPI via Trusted Publishers (OIDC) whenever a GitHub Release is published:

```bash
gh release create v1.1.0 \
  --title "v1.1.0 — Hosted Backend, Docker Build, Client Mode" \
  --notes "See release notes for details."
```

Configure a Trusted Publisher on PyPI pointing at this repository before your first publish.

---

## Development

Run the test suite:

```bash
python -m pytest
```

### Project Structure

```
reviewer/
  analyzer.py        Review orchestration: chunked analysis, merging, client/direct modes
  parser.py          tree-sitter AST extraction and logical chunking
  prompt_builder.py  LLM prompt construction with schema + guidelines
  guidelines.py      .ai-review.toml / guidelines.md loading
  git_utils.py       Git diff extraction and repo root resolution
  reporter.py        text / JSON output formatting
  server.py          Hosted backend (ai-review-server)
main.py              CLI entry point (ai-code-review)
tests/               Unit + integration tests (pytest)
```
