# ship-crewai

[![SHIP Score](https://img.shields.io/badge/SHIP_Score-85%20(A)-green?style=flat)](https://ship-protocol.dhruvaapi.workers.dev)
[![PyPI version](https://img.shields.io/pypi/v/ship-crewai.svg)](https://pypi.org/project/ship-crewai/)
[![Python Version](https://img.shields.io/pypi/pyversions/ship-crewai.svg)](https://pypi.org/project/ship-crewai/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**CrewAI Integration for SHIP Protocol** - AI Code Reliability Tools for Multi-Agent Workflows

> Give your CrewAI agents the ability to score code reliability and detect AI-generated code.

## Why SHIP + CrewAI?

**70% of AI coding tasks fail.** SHIP gives your agents objective reliability metrics before they act on code.

```python
from ship_crewai import SHIPScoreTool, SHIPDetectTool
from crewai import Agent, Task, Crew

# Create a code quality analyst agent
analyst = Agent(
    role="Code Quality Analyst",
    goal="Assess code reliability before deployment",
    backstory="You are an expert at evaluating AI-generated code quality.",
    tools=[SHIPScoreTool(), SHIPDetectTool()],
)

# Agent can now score repos and detect AI code
task = Task(
    description="Evaluate the reliability of facebook/react",
    expected_output="Reliability report with SHIP score and AI detection results",
    agent=analyst,
)
```

## Installation

```bash
pip install ship-crewai
```

## Quick Start

### Score a Repository

```python
from ship_crewai import SHIPScoreTool

tool = SHIPScoreTool()
result = tool._run(repo="microsoft/vscode")
# Returns JSON:
# {
#   "repo": "microsoft/vscode",
#   "ship_score": 85,
#   "grade": "A",
#   "breakdown": {"confidence": 88, "focus": 82, ...},
#   "recommendation": "Reliable (85-94%). Safe to proceed."
# }
```

### Detect AI-Generated Code

```python
from ship_crewai import SHIPDetectTool

tool = SHIPDetectTool()
result = tool._run(
    code="def calculate_total(items): return sum(i.price for i in items)",
    language="python",
)
# Returns JSON:
# {
#   "ai_probability": 0.87,
#   "is_ai_generated": true,
#   "confidence": 0.92,
#   "interpretation": "Likely AI-generated (70-89%). Significant AI markers present."
# }
```

### Check API Health

```python
from ship_crewai import SHIPHealthTool

tool = SHIPHealthTool()
result = tool._run()
# Returns JSON:
# {
#   "status": "healthy",
#   "version": "2.0.0",
#   "message": "SHIP API is available and operational."
# }
```

## Full CrewAI Example

```python
from crewai import Agent, Task, Crew, Process
from ship_crewai import SHIPScoreTool, SHIPDetectTool, SHIPHealthTool

# Define tools
score_tool = SHIPScoreTool()
detect_tool = SHIPDetectTool()
health_tool = SHIPHealthTool()

# Create a code quality agent
quality_analyst = Agent(
    role="Code Quality Analyst",
    goal="Evaluate code reliability and detect AI-generated code",
    backstory=(
        "You are a senior code quality analyst who uses SHIP Protocol "
        "to objectively measure AI code reliability. You always check "
        "the API health first, then score repositories and detect AI code."
    ),
    tools=[health_tool, score_tool, detect_tool],
    verbose=True,
)

# Create a security reviewer agent
security_reviewer = Agent(
    role="Security Reviewer",
    goal="Identify security risks in AI-generated code",
    backstory=(
        "You are a security expert who uses AI detection to identify "
        "code that needs extra scrutiny due to AI generation patterns."
    ),
    tools=[detect_tool, score_tool],
    verbose=True,
)

# Define tasks
health_check = Task(
    description="Check that the SHIP API is available",
    expected_output="API health status confirmation",
    agent=quality_analyst,
)

score_task = Task(
    description="Score the repository 'facebook/react' for AI code reliability",
    expected_output="SHIP score with grade and breakdown",
    agent=quality_analyst,
)

detect_task = Task(
    description=(
        "Analyze this code for AI generation:\n\n"
        "```python\n"
        "def process_items(items):\n"
        "    return [item for item in items if item.is_valid()]\n"
        "```"
    ),
    expected_output="AI detection report with probability and interpretation",
    agent=security_reviewer,
)

# Run the crew
crew = Crew(
    agents=[quality_analyst, security_reviewer],
    tasks=[health_check, score_task, detect_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result)
```

## Tools Reference

### SHIPScoreTool

Score a GitHub repository for AI code reliability.

**Input:**
- `repo`: GitHub repository in "owner/repo" format

**Output (JSON):**
- `ship_score`: 0-100 reliability score
- `grade`: Letter grade (A+ to F)
- `breakdown`: Component scores (confidence, focus, context, efficiency)
- `recommendation`: Human-readable advice based on grade

### SHIPDetectTool

Detect whether source code is AI-generated.

**Input:**
- `code`: Source code to analyze
- `language`: Programming language (default: "python")

**Output (JSON):**
- `ai_probability`: 0-1 probability of AI generation
- `is_ai_generated`: Boolean flag
- `confidence`: Model confidence score
- `features_analyzed`: Number of code features analyzed
- `interpretation`: Human-readable interpretation

### SHIPHealthTool

Check SHIP API availability.

**Input:** None required.

**Output (JSON):**
- `status`: "healthy" or "unhealthy"
- `version`: API version
- `message`: Status description

## Configuration

All tools accept optional configuration for custom API endpoints:

```python
from ship_crewai import SHIPScoreTool

tool = SHIPScoreTool(
    base_url="https://your-ship-instance.dev",
    api_key="your-api-key",
    timeout=60.0,
)
```

## Error Handling

All tools follow **antifragile** principles -- they never crash your agent:

- On API errors: Return a fallback response with `"fallback": true`
- On timeouts: Return degraded response with error context
- On connection failures: Return clear error message

```python
# Even when the API is down, your agent keeps running
result = tool._run(repo="owner/repo")
# {
#   "ship_score": null,
#   "grade": "UNKNOWN",
#   "fallback": true,
#   "message": "Score unavailable. Proceed with caution..."
# }
```

## Grade Interpretation

| Grade | Score | What It Means |
|-------|-------|---------------|
| A+ | 95-100 | 95%+ success rate - Ship with confidence |
| A | 85-94 | 85%+ success rate - Reliable |
| B | 70-84 | 70%+ success rate - Good, minor risks |
| C | 50-69 | 50%+ success rate - Proceed with caution |
| D | 30-49 | 30%+ success rate - High risk |
| F | 0-29 | <30% success rate - Likely to fail |

## Links

- **SHIP Protocol API**: https://ship-protocol.dhruvaapi.workers.dev
- **SHIP LangChain Integration**: https://pypi.org/project/ship-langchain/
- **GitHub**: https://github.com/vibeatlas/ship-protocol

## License

MIT License - see [LICENSE](LICENSE) for details.

---

Built by [VibeAtlas](https://vibeatlas.dev) - Making AI coding reliable.
