# Contributing to Alive

We welcome contributions. Alive is a young project and there's a lot to build.

## Quick Start

```bash
git clone https://github.com/darshanahirrao/Alive.git
cd Alive
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

## What to Work On

- **Good first issues** are labeled in the issue tracker
- **ALP implementations** in other languages (Rust, Go, TypeScript) are especially welcome
- **New integrations** that compose with the existing 5
- **Skill contributions** via `alive share` and `alive install`

## Code Style

- Python 3.11+, type hints everywhere
- `async` for LLM calls, sync elsewhere
- `rich` for all terminal output
- No classes where functions suffice
- Lazy imports for optional dependencies
- Error messages should be helpful and suggest next steps

## Testing

Every PR must pass the full test suite:

```bash
pytest tests/ -v
```

We use `unittest.mock` extensively. External services (APIs, network, filesystem) must be mocked. If you add a new module, add a corresponding test file.

Current coverage: 657 tests across 31 test files.

## Pull Request Process

1. Fork the repo and create a feature branch
2. Write your code and tests
3. Run `pytest tests/ -v` and ensure all tests pass
4. Submit a PR with a clear description of what and why
5. One maintainer review required for merge

## Project Structure

```
src/alive/
  core/           # Planner, composer, skill builder, registry, chains, graph
  integrations/   # Web search, Telegram, scheduler, browser, webhooks
  network/        # ALP: identity, discovery, server, exchange, security
  llm/            # Multi-provider LLM abstraction
  memory/         # Per-skill persistent storage
  sandbox/        # Subprocess execution + dependency management
  sharing/        # Export/import skills as archives
  cli.py          # Typer CLI entry point (45+ commands)
tests/
  test_network/   # ALP network layer tests
  test_*.py       # Module-level test files
```

## ALP Protocol Contributions

If you're implementing ALP in another language or platform:

1. Read the [ALP Specification](docs/ALP_SPEC.md)
2. Implement the 3 HTTP endpoints (`/alp/card`, `/alp/skills`, `/alp/skill/<name>`)
3. Implement UDP discovery on port 51966
4. Open an issue with `alp-implementation` label so we can link your project

## License

By contributing, you agree that your contributions will be licensed under the MIT License.
