# ship-score

**SHIP Protocol** — AI code reliability scoring for Python.

Score AI-generated commits, detect AI-written code, and gate commits via pre-commit hooks.

## Install

```bash
pip install ship-score
```

## CLI Usage

### Score a commit

```bash
ship-score score --repo owner/repo --message "feat: add user auth" --language python
# SHIP Score: 73/100 (Grade: B) | Confidence: 0.82
```

### Detect AI-generated code

```bash
ship-score detect --file main.py
# AI-Generated: Yes (89% confidence) | 174 features analyzed
```

### Generate a report

```bash
ship-score report owner/repo
```

### Check API health

```bash
ship-score health
# ✓ API reachable: https://ship-protocol.dhruvaapi.workers.dev
#   Commits: 22,060
#   Repos:   10,003
```

### List AI tool rankings

```bash
ship-score tools
```

### JSON output

Add `--json` to `score` or `detect` for machine-readable output:

```bash
ship-score score --repo owner/repo --message "fix: bug" --json
```

## Library Usage

```python
from ship_score import ShipClient

client = ShipClient()

# Score a commit
score = client.score(repo="owner/repo", message="feat: add auth", language="python")
print(score.score, score.grade)  # 73, "B"
print(score.confidence)          # 0.82
print(score.recommendations)     # ["Add tests", ...]

# Detect AI-generated code
detection = client.detect(code=open("main.py").read(), language="python")
print(detection.is_ai, detection.confidence)  # True, 0.89

# List AI tool rankings
tools = client.tools()
for tool in tools:
    print(f"{tool.display_name}: {tool.grade}")

# Health check
health = client.health()
print(health.api_reachable, health.total_commits)
```

### Custom API URL

```python
client = ShipClient(base_url="https://your-instance.example.com")
```

Or set the `SHIP_API_URL` environment variable for the CLI.

## Pre-commit Hook

Add to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/vibeatlas/ship-score-python
    rev: v1.0.0
    hooks:
      - id: ship-score
        args: ['--min-score=60']
```

The hook:
- Extracts the staged commit message and changed file languages
- Scores via the SHIP API
- **Blocks the commit** if the score is below the threshold (default: 60)
- Prints recommendations on how to improve

## API Reference

The package wraps the [SHIP Protocol API](https://ship-protocol.dhruvaapi.workers.dev):

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v2/score` | POST | Score an AI-generated commit |
| `/v2/detect` | POST | Detect AI-generated code |
| `/v2/tools` | GET | AI tool reliability rankings |
| `/v2/crawler-status` | GET | Data pipeline stats |

## Development

```bash
git clone https://github.com/vibeatlas/ship-score-python.git
cd ship-score-python
pip install -e ".[dev]"
pytest
mypy ship_score/
ruff check .
```

## License

MIT
