auto-commit-service/README.md

# Auto-Commit Service

Automated commit message generation service using local LLM inference. Commits and pushes changes across lilith-platform repos every 15 minutes.

## Features

- Generates commit messages using llama-service (local 3B model)
- Processes multiple repositories in a cycle
- Automatic push with conflict resolution
- Claude Code fallback for complex failures
- FastAPI endpoints for monitoring and manual triggers
- **CLI for multi-daemon management** (`commits` command)

## Installation

```bash
# Install the package
cd /var/home/lilith/Code/@packages/@ml/auto-commit-service
pip install -e .

# Or with model-boss integration (recommended)
pip install -e ".[model-boss]"

# Or with dev dependencies
pip install -e ".[dev]"
```

After installation, the `commits` CLI is available system-wide.

### Model Configuration

The service requires a language model to generate commit messages. You have three options:

1. **Auto-load via model-boss (recommended)**:
   ```bash
   pip install -e ".[model-boss]"
   # Models will be auto-downloaded and cached
   # Default: ministral-3b-instruct
   ```

2. **Manual model path**:
   ```bash
   export LLAMA_SERVICE_MODEL_PATH=/path/to/model.gguf
   ```

3. **Disable auto-start** (use external llama-service):
   ```bash
   export AUTO_COMMIT_LLAMA_SERVICE_AUTOSTART=false
   ```

**Important**: If no model is configured, the service will fail to start and report as down. This prevents making commits with placeholder messages.

## CLI Usage

The `commits` CLI manages multiple auto-commit daemon instances.

### Quick Start

```bash
# Start daemon for current directory
cd ~/Code/@packages
commits start 5m -R              # Every 5 min, recursive discovery

# Check status
commits status                   # Current directory
commits status --all             # All daemons

# View report
commits report                   # Comprehensive report
commits report -A                # All daemons summary

# Trigger immediate cycle
commits once                     # Refresh repos and commit
commits once -A                  # All daemons

# Stop daemon
commits stop
```

### Commands

| Command | Description |
|---------|-------------|
| `commits start [interval] [OPTIONS]` | Start daemon for current directory |
| `commits stop` | Stop daemon for current directory |
| `commits status [-A]` | Show daemon status |
| `commits once [-A]` | Refresh repos and trigger cycle |
| `commits report [-A] [-C N] [--raw]` | Show comprehensive report |
| `commits trigger` | Manually trigger a commit cycle |
| `commits enable` | Enable the daemon |
| `commits disable` | Disable the daemon |
| `commits logs` | Tail daemon logs |
| `commits list` | List all running daemons |
| `commits install-systemd DIR [OPTIONS]` | Install systemd user service |

### Start Options

```bash
commits start [interval] [OPTIONS]

Options:
  -R, --recursive        Enable recursive git discovery
  --depth INT            Recursion depth limit
  -C, --cache-update STR Cache refresh interval (default: 60m)

Examples:
  commits start 5m              # Every 5 minutes
  commits start -R 1h           # Every hour, recursive
  commits start -R --depth 1 5m # Every 5 min, depth 1
```

### Report Options

```bash
commits report [OPTIONS]

Options:
  -A, --all-daemons    Show reports for all daemons
  -C INT               Show last N commits grouped by repo
  --raw                Show raw JSON output

Examples:
  commits report             # Summary for current directory
  commits report -A          # Summary for all daemons
  commits report -C 20       # Last 20 commits
```

### Systemd Integration

```bash
# Install systemd user service
commits install-systemd ~/Code/@packages 5m -R

# Service commands
systemctl --user status commits-var-home-lilith-Code-@packages
systemctl --user stop commits-var-home-lilith-Code-@packages
journalctl --user -u commits-var-home-lilith-Code-@packages -f
```

## Configuration

Environment variables (prefix: `AUTO_COMMIT_`):

| Variable | Default | Description |
|----------|---------|-------------|
| `AUTO_COMMIT_LLAMA_SERVICE_URL` | `http://localhost:8000` | llama-service URL |
| `AUTO_COMMIT_LLAMA_SERVICE_AUTOSTART` | `true` | Auto-start llama-service if down |
| `AUTO_COMMIT_LLAMA_MODEL_ID` | `qwen2.5-1.5b-instruct` | Model ID for model-boss |
| `AUTO_COMMIT_USE_MODEL_BOSS` | `true` | Use model-boss for model loading |
| `AUTO_COMMIT_CYCLE_INTERVAL_SECONDS` | `900` | Seconds between cycles (15 min) |
| `AUTO_COMMIT_ENABLED` | `true` | Enable daemon on startup |
| `AUTO_COMMIT_CLAUDE_FALLBACK_ENABLED` | `true` | Enable Claude Code recovery |
| `AUTO_COMMIT_HOST` | `0.0.0.0` | Service host |
| `AUTO_COMMIT_PORT` | `8200` | Service port |

## Direct Service Usage

If you prefer to run the service directly without the CLI:

### Run directly

```bash
python -m auto_commit_service
```

### Run with uvicorn

```bash
uvicorn auto_commit_service:create_auto_commit_service --host 0.0.0.0 --port 8200
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Service health check |
| `/status` | GET | Daemon status and last cycle |
| `/trigger` | POST | Manually trigger a cycle |
| `/enable` | POST | Enable the daemon |
| `/disable` | POST | Disable the daemon |
| `/repos` | GET | List configured repositories |
| `/repos/refresh-and-run` | POST | Refresh repo cache and trigger cycle |
| `/report/summary` | GET | Comprehensive daemon report |
| `/report/commits` | GET | Commit history |

### Examples

```bash
# Check health
curl http://localhost:8200/health

# Get status
curl http://localhost:8200/status

# Trigger manual cycle
curl -X POST http://localhost:8200/trigger

# Disable daemon
curl -X POST http://localhost:8200/disable
```

## Commit Style

Generated commits follow the Lilith Platform convention:

- `✨` feat: New feature
- `🔧` chore: Maintenance, config changes
- `♻️` refactor: Code restructuring
- `🐛` fix: Bug fix
- `📝` docs: Documentation
- `✅` test: Tests
- `🔥` remove: Removing code/files

## Error Handling

1. **No model configured**: Service fails to start, reported as down (prevents bad commits)
2. **Push rejected**: Attempts `git pull --rebase` and retries
3. **Merge conflict**: Invokes Claude Code to resolve
4. **Hook failure**: Invokes Claude Code to fix
5. **LLM unavailable**: Service auto-starts if configured, otherwise skips cycle
6. **Infrastructure errors** (network, auth): Skips Claude recovery, reports error
7. **Auth failure**: Skips repo (requires manual fix)

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=auto_commit_service
```

## Architecture

```
auto_commit_service/
├── __init__.py         # Package exports
├── __main__.py         # Entry point
├── app.py              # FastAPI application factory
├── config.py           # Settings (AutoCommitSettings)
├── models.py           # Pydantic models
├── cli/                # CLI module
│   ├── __init__.py     # Typer app and commands
│   ├── registry.py     # Daemon registry management
│   └── utils.py        # CLI utilities
├── git/
│   ├── operations.py   # Async git commands
│   ├── repository.py   # Repository abstraction
│   └── diff_parser.py  # Diff summarization
├── llm/
│   ├── client.py       # llama-service HTTP client
│   └── prompts.py      # Commit message prompts
├── scheduler/
│   ├── daemon.py       # Main 900s loop
│   └── processor.py    # Per-repo commit logic
└── recovery/
    ├── handlers.py     # Error type routing
    └── claude_fallback.py  # Claude Code invocation
```

## Dependencies

- `lilith-ml-service-base`: FastAPI patterns, lifespan, health checks
- `httpx`: Async HTTP client for llama-service
- `pydantic`: Configuration and models
- `uvicorn`: ASGI server
- `typer`: CLI framework

## Configuration Files

| File | Location | Purpose |
|------|----------|---------|
| Daemon registry | `~/.config/commits/daemons.json` | Tracks running daemon instances |
| Logs | `/tmp/auto-commit-{port}.log` | Per-daemon log files |