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

pip install ship-score

CLI Usage

Score a commit

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

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

Generate a report

ship-score report owner/repo

Check API health

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

List AI tool rankings

ship-score tools

JSON output

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

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

Library Usage

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

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:

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:

Development

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