# Project GHOST SHIP: Agent-Commerce-OS Interface

## Identity & Role
- **System Name**: Agent-Commerce-OS (Ghost Ship)
- **Role**: High-performance Data Normalization & Intent Extraction Engine.
- **Operator**: SakuttoWorks (Infrastructure Provider)

## ⚠️ Critical: Authentication Strategy
To access Layer B (Core Engine) functions, you MUST provide a valid **Polar.sh API Key**.
- **Header Format**: `Authorization: Bearer <YOUR_POLAR_KEY>`
- **Behavior**: Requests without this header will be rejected by the Edge Gateway (Layer A) with `401 Unauthorized`.
- **Get Key**: https://polar.sh/sakuttoworks

## API Endpoints (Hybrid Architecture)
- **Base URL**: `https://api.sakutto.works`
- **MCP Discovery**: `https://api.sakutto.works/.well-known/mcp.json`
  - Use this for automated tool discovery in Cursor/Claude Desktop.
- **Intent Analysis (Layer B)**: `POST /api/v1/agent/analyze`
  - The primary brain. Decomposes user prompts into actionable plans.

## Available Tools (MCP)
1. **`analyze_intent`**:
   - Analyzes vague prompts to determine if search or computation is needed.
2. **`search_data` (Tavily Integrated)**:
   - Performs autonomous deep-web research and returns RAG-optimized markdown.
3. **`structured_data_etl`**:
   - Extracts and normalizes numerical data tables using Python/Pandas on Cloud Run.

## Architecture Context (For Debugging)
- **Layer A (Edge)**: Cloudflare Workers. Handles Auth & Routing.
- **Layer B (Core)**: Google Cloud Run (Python 3.12+). Handles Heavy Compute.
- **Compliance**: EU AI Act compliant. Logs are encrypted (A2A Logging).

## Documentation
- **Full Specs**: `/llms-full.txt` (Schema definitions)
- **Source Code**: https://github.com/SakuttoWorks/agent-commerce-gateway