API Documentation

curl -X POST https://app.arcus-ai.app/api/copilot/check \
  -H "Authorization: Bearer arc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "system_description": "An AI hiring tool that screens resumes",
    "use_case": "hiring",
    "deployment_regions": ["eu", "us_colorado"]
  }'

Authorization: Bearer arc_your_api_key_here

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

pip install arcus-copilot

from arcus_copilot import CopilotClient

client = CopilotClient(api_key="arc_your_api_key")

# Analyze an AI system for compliance
result = client.check(
    system_description="An AI hiring tool that screens resumes",
    use_case="hiring",
    data_types=["personal_data", "employment_history"],
    deployment_regions=["eu", "us_colorado"],
)

print(f"Risk Level: {result.risk_level}")
print(f"Confidence: {result.confidence}")

for obligation in result.key_obligations:
    print(f"  [{obligation.priority}] {obligation.title}")

# Get compliance status for a registered system
status = client.get_system_status("550e8400-e29b-41d4-a716-446655440000")

print(f"Overall Score: {status.compliance.overall_score}")
print(f"Open Alerts: {status.alerts.total_open}")

"""
Arcus Developer Compliance Copilot - Python SDK Stub
"""

import requests
from dataclasses import dataclass, field
from typing import Optional


@dataclass
class Jurisdiction:
    jurisdiction_key: str
    jurisdiction_name: str
    risk_classification: str
    applicable: bool
    reason: str


@dataclass
class Obligation:
    title: str
    description: str
    jurisdiction: str
    priority: str
    legal_reference: str
    deadline_info: Optional[str] = None


@dataclass
class Recommendation:
    title: str
    description: str
    urgency: str
    estimated_effort: str


@dataclass
class CheckMeta:
    model_used: str
    analysis_time_ms: int
    input_tokens: int
    output_tokens: int


@dataclass
class CheckResult:
    risk_level: str
    confidence: float
    applicable_jurisdictions: list[Jurisdiction]
    key_obligations: list[Obligation]
    recommendations: list[Recommendation]
    summary: str
    meta: Optional[CheckMeta] = None


@dataclass
class ObligationSummary:
    total: int
    met: int
    unmet: int
    in_progress: int


@dataclass
class JurisdictionScore:
    jurisdiction_key: str
    score: float
    component_scores: Optional[dict] = None
    computed_at: Optional[str] = None


@dataclass
class Compliance:
    overall_score: Optional[float]
    jurisdiction_scores: list[JurisdictionScore]
    obligation_summary: ObligationSummary


@dataclass
class RiskAssessment:
    latest_classification: Optional[str]
    confidence_score: Optional[float]
    assessed_at: Optional[str]


@dataclass
class Alerts:
    total_open: int
    by_severity: dict


@dataclass
class Watchtower:
    active_alerts: int
    threshold_violations: int


@dataclass
class SystemInfo:
    id: str
    name: str
    description: Optional[str]
    purpose: Optional[str]
    deployment_status: Optional[str]
    jurisdiction_flags: list[str]
    status: Optional[str]
    created_at: str
    updated_at: str


@dataclass
class SystemStatus:
    system: SystemInfo
    compliance: Compliance
    risk_assessment: RiskAssessment
    alerts: Alerts
    watchtower: Watchtower


class CopilotError(Exception):
    def __init__(self, code: str, message: str, status_code: int):
        super().__init__(message)
        self.code = code
        self.status_code = status_code


class CopilotClient:
    def __init__(
        self,
        api_key: str,
        base_url: str = "https://app.arcus-ai.app",
        timeout: int = 60,
    ):
        self._api_key = api_key
        self._base_url = base_url.rstrip("/")
        self._timeout = timeout
        self._session = requests.Session()
        self._session.headers.update(
            {
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json",
            }
        )

    def check(
        self,
        system_description: str,
        use_case: Optional[str] = None,
        data_types: Optional[list[str]] = None,
        deployment_regions: Optional[list[str]] = None,
        affected_individuals: Optional[str] = None,
        risk_category: Optional[str] = None,
    ) -> CheckResult:
        payload = {"system_description": system_description}
        if use_case:
            payload["use_case"] = use_case
        if data_types:
            payload["data_types"] = data_types
        if deployment_regions:
            payload["deployment_regions"] = deployment_regions
        if affected_individuals:
            payload["affected_individuals"] = affected_individuals
        if risk_category:
            payload["risk_category"] = risk_category

        response = self._session.post(
            f"{self._base_url}/api/copilot/check",
            json=payload,
            timeout=self._timeout,
        )

        data = response.json()
        if not data.get("success"):
            err = data.get("error", {})
            raise CopilotError(
                code=err.get("code", "UNKNOWN"),
                message=err.get("message", "Unknown error"),
                status_code=response.status_code,
            )

        result_data = data["data"]
        return CheckResult(
            risk_level=result_data["risk_level"],
            confidence=result_data["confidence"],
            applicable_jurisdictions=[
                Jurisdiction(**j)
                for j in result_data.get("applicable_jurisdictions", [])
            ],
            key_obligations=[
                Obligation(**o) for o in result_data.get("key_obligations", [])
            ],
            recommendations=[
                Recommendation(**r)
                for r in result_data.get("recommendations", [])
            ],
            summary=result_data.get("summary", ""),
            meta=CheckMeta(**data["meta"]) if "meta" in data else None,
        )

    def get_system_status(self, system_id: str) -> SystemStatus:
        response = self._session.get(
            f"{self._base_url}/api/copilot/systems/{system_id}/status",
            timeout=self._timeout,
        )

        data = response.json()
        if not data.get("success"):
            err = data.get("error", {})
            raise CopilotError(
                code=err.get("code", "UNKNOWN"),
                message=err.get("message", "Unknown error"),
                status_code=response.status_code,
            )

        d = data["data"]
        return SystemStatus(
            system=SystemInfo(**d["system"]),
            compliance=Compliance(
                overall_score=d["compliance"]["overall_score"],
                jurisdiction_scores=[
                    JurisdictionScore(**s)
                    for s in d["compliance"]["jurisdiction_scores"]
                ],
                obligation_summary=ObligationSummary(
                    **d["compliance"]["obligation_summary"]
                ),
            ),
            risk_assessment=RiskAssessment(**d["risk_assessment"]),
            alerts=Alerts(**d["alerts"]),
            watchtower=Watchtower(**d["watchtower"]),
        )

    @property
    def rate_limit_info(self) -> dict:
        return {
            "limit": self._session.headers.get("X-RateLimit-Limit"),
            "remaining": self._session.headers.get("X-RateLimit-Remaining"),
            "reset": self._session.headers.get("X-RateLimit-Reset"),
        }