# earlyai-agent

AI-powered automatic unit test generation for Python, by [Early](https://www.startearly.ai).

`earlyai-agent` is the Python analysis engine used by the [Early CLI](https://docs.startearly.ai/docs/agent-fundamentals/agents-npm-authentication) to generate green (passing) unit tests. It analyzes your source code, identifies public functions and methods, and generates pytest tests using AI.

> **Note:** `earlyai-agent` is a dependency of the Early CLI and is not intended to be used standalone. Install and operate it through the Early CLI.

## Installation

### 1. Install the Early CLI

```bash
npm install -g @earlyai/cli
```

See the [CLI Installation Guide](https://docs.startearly.ai/docs/agent-fundamentals/agents-npm-authentication) for details.

### 2. Install earlyai-agent

```bash
pip install earlyai-agent
```

**Requirements:** Python 3.11+

### 3. Get an API Key

You need an EarlyAI API key to use the agent. Contact [support@startearly.ai](mailto:support@startearly.ai) or visit [www.startearly.ai](https://www.startearly.ai) to get one.

## Usage

All commands are run through the Early CLI. See the full [CLI documentation](https://docs.startearly.ai/docs/early-catch-pr-cli/cli-introduction) for all options.

### Generate tests for a project

```bash
early generate-project \
  --api-key <your-api-key> \
  --token <your-github-token> \
  --target-directory src/ \
  --ref-name <branch-name> \
  --test-framework pytest
```

See the [Repo CLI Guide](https://docs.startearly.ai/docs/early-catch-repo-cli/repo-cli-introduction) for more details.

### Generate tests on a pull request

```bash
early generate-pr \
  --api-key <your-api-key> \
  --token <your-github-token> \
  --pr-number 123 \
  --ref-name feature/my-branch \
  --test-framework pytest
```

See the [PR CLI Guide](https://docs.startearly.ai/docs/early-catch-pr-cli/cli-introduction) for more details.

### Run locally

For quick local evaluation, see [Running Early CLI Locally](https://docs.startearly.ai/docs/agent-onboarding/repo-cli-run-locally).

## Configuration

All options can be set via CLI flags or environment variables:

| Flag | Env Variable | Default | Description |
|------|-------------|---------|-------------|
| `--api-key` | `API_KEY` | -- | EarlyAI API key (**required**) |
| `--token` | `TOKEN` | -- | GitHub token for commits/PRs (**required**) |
| `--target-directory` | `TARGET_DIRECTORY` | `.` | File or directory to generate tests for |
| `--test-framework` | `TEST_FRAMEWORK` | `pytest` | Test framework (`pytest`) |
| `--test-structure` | `TEST_STRUCTURE` | `siblingFolder` | Where to place tests (`siblingFolder`, `rootFolder`) |
| `--max-concurrency` | `MAX_CONCURRENCY` | `3` | Number of concurrent workers |
| `--max-testables` | `MAX_TESTABLES` | unlimited | Max methods to generate tests for |

For the full configuration reference, see [CLI Configuration](https://docs.startearly.ai/docs/early-catch-pr-cli/cli-configuration).

### Test file placement

- **`siblingFolder`** (default): Tests are placed in a folder next to the source file
  ```
  src/services/user.py
  src/services/user.early.test/test_get_user.py
  ```
- **`rootFolder`**: Tests are placed in a root `tests/` directory mirroring the source structure

## CI/CD Integration

### GitHub Actions (PR)

Add to `.github/workflows/early-pr-test-generation.yml`:

```yaml
name: Early PR Test Generation

permissions:
  contents: write
  pull-requests: write
  packages: read

on:
  pull_request:
    types: [opened, reopened, synchronize]
    branches: [main]

jobs:
  early-test-generation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: |
          pip install earlyai-agent
          npm install -g @earlyai/cli

      - name: Generate tests
        continue-on-error: true
        env:
          API_KEY: ${{ secrets.EARLY_AGENT_API_KEY }}
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REF_NAME: ${{ github.head_ref }}
          BASE_REF: ${{ github.base_ref }}
          TEST_FRAMEWORK: pytest
        run: early generate-pr
```

For other CI/CD systems (Jenkins, CircleCI, Bitbucket Pipelines), see the [Agent Onboarding Guide](https://docs.startearly.ai/docs/agent-onboarding/introduction).

## How It Works

1. **Scan** -- Discovers Python source files in the target directory
2. **Extract** -- Analyzes each file to identify public functions and methods
3. **Generate** -- Uses AI to generate unit tests for each function
4. **Validate** -- Runs generated tests with pytest, keeping only green (passing) tests

## Troubleshooting

- [Troubleshooting Common Failures](https://docs.startearly.ai/docs/agent-fundamentals/agents-troubleshooting)
- [Why Were No Tests Generated?](https://docs.startearly.ai/docs/agent-fundamentals/agents-no-tests-generated)
- [FAQ](https://docs.startearly.ai/docs/agent-fundamentals/agents-faq)

## Support

- Documentation: [docs.startearly.ai](https://docs.startearly.ai)
- Email: [support@startearly.ai](mailto:support@startearly.ai)
- Website: [www.startearly.ai](https://www.startearly.ai)

## License

Commercial
