vibeatlas-ship

SHIP Protocol SDK - Success Heuristics for Intelligent Programming

The industry standard for measuring AI coding agent reliability.

Why SHIP?

70% of AI coding tasks fail. There's no standard metric for reliability.

SHIP Score (0-100) predicts whether AI-assisted code will work:

Grade	Score	Reliability
A+	95-100	95%+ success rate
A	85-94	85-94% success rate
B	70-84	70-84% success rate
C	50-69	50-69% success rate
D	30-49	30-49% success rate
F	0-29	<30% success rate

Installation

pip install vibeatlas-ship

Quick Start

Async (Recommended)

import asyncio
from vibeatlas_ship import ShipClient, FileInfo, Language

async def main():
    async with ShipClient() as client:
        response = await client.assess(
            files=[
                FileInfo(
                    path="main.py",
                    content='''
def calculate_total(items):
    return sum(item.price for item in items)
                    ''',
                    language=Language.PYTHON,
                )
            ],
            prompt="Add error handling and type hints",
        )

        # Get your SHIP Score
        print(f"SHIP Score: {response.ship_score.score} ({response.ship_score.grade.value})")
        print(f"Confidence: {response.confidence.confidence_score}")
        print(f"Focus: {response.focus.focus_score}")
        print(f"Context: {response.context.context_score}")
        print(f"Efficiency: {response.efficiency.efficiency_score}")

        # Get recommendations
        for rec in response.recommendations:
            print(f"  [{rec.type}] {rec.message}")

asyncio.run(main())

Sync Client

from vibeatlas_ship import SyncShipClient, FileInfo, Language

with SyncShipClient() as client:
    response = client.quick_assess(
        code="def hello(): print('world')",
        prompt="Add type hints and docstring",
        language=Language.PYTHON,
    )
    print(f"SHIP Score: {response.ship_score.score}")

From Files

from vibeatlas_ship import SyncShipClient

with SyncShipClient() as client:
    response = client.assess_files(
        file_paths=["src/main.py", "src/utils.py"],
        prompt="Refactor to use async/await",
        project_root="/path/to/project",
    )

Features

Antifragile Design

Built with Talebian principles - the SDK gets stronger from failures:

• Circuit Breaker: Prevents cascade failures
• Exponential Backoff: Smart retry with jitter
• Graceful Degradation: Never crashes, always returns useful info

from vibeatlas_ship import ShipClientConfig, CircuitBreaker, RetryPolicy

config = ShipClientConfig(
    # Circuit breaker settings
    circuit_breaker=CircuitBreaker(
        failure_threshold=5,
        failure_window_seconds=60,
        recovery_timeout_seconds=30,
    ),
    # Retry settings
    retry_policy=RetryPolicy(
        max_retries=3,
        base_delay_ms=1000,
        max_delay_ms=30000,
    ),
)

client = ShipClient(config)

Self-Learning Feedback Loop

Help improve the model by providing feedback:

from vibeatlas_ship import TaskOutcome

# After your AI task completes
await client.feedback(
    request_id=response.request_id,
    outcome=TaskOutcome(
        task_completed=True,
        first_attempt_success=True,
        total_attempts=1,
        user_satisfaction=5,
    ),
)

Full Type Safety

Complete type hints and Pydantic validation:

from vibeatlas_ship import (
    ShipResponse,
    ShipScore,
    ConfidenceAssessment,
    FocusAssessment,
)

# All types are fully typed and validated
response: ShipResponse = await client.assess(...)
score: ShipScore = response.ship_score
confidence: ConfidenceAssessment = response.confidence

API Reference

ShipClient

Method	Description
assess()	Assess code context and get SHIP Score
quick_assess()	Quick assessment from single code snippet
assess_files()	Assess files from disk
feedback()	Submit feedback for learning
get_score()	Get project's current score
get_metrics()	Get account metrics
health()	Check API health

Types

Type	Description
FileInfo	File with content and metadata
Context	Context for assessment
ShipScore	Score breakdown
ShipResponse	Full assessment response
TaskOutcome	Feedback outcome data

Exceptions

Exception	Description
ShipError	Base exception
ShipTimeoutError	Request timed out
ShipRateLimitError	Rate limit exceeded
ShipValidationError	Invalid request
CircuitBreakerOpenError	Circuit breaker open

Configuration

from vibeatlas_ship import ShipClientConfig, create_client

client = create_client(
    api_key="ship_free_...",  # Optional for free tier
    base_url="https://ship.vibeatlas.dev",
    timeout_seconds=30,
)

Environment variables:

export SHIP_API_KEY="ship_free_..."
export SHIP_BASE_URL="https://ship.vibeatlas.dev"

Philosophy

This SDK follows Talebian/Antifragile principles:

1. Optionality: Multiple ways to achieve the same goal
2. Barbell Strategy: Safe defaults + advanced configuration
3. Via Negativa: Improve by removing failure modes
4. Convexity: Failures cost little, successes compound
5. Skin in the Game: Confidence scores = accountability

Links

• Documentation: https://vibeatlas.dev/docs/ship
• API Reference: https://ship.vibeatlas.dev
• GitHub: https://github.com/vibeatlas/ship-protocol
• npm Package: https://www.npmjs.com/package/@vibeatlas/ship-protocol

License

MIT License - see LICENSE for details.

---

Built with love by VibeAtlas - Making AI coding reliable.