Metadata-Version: 2.4
Name: agent-skill-compiler
Version: 0.1.0
Summary: Local-first toolkit for mining repeated multi-agent execution patterns into candidate skills.
Author: Open Source Contributors
License: MIT
Keywords: agents,ai,analysis,skills,tooling,tracing
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: pydantic>=2.11.0
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.15.3
Requires-Dist: uvicorn>=0.34.0
Description-Content-Type: text/markdown

# Agent Skill Compiler

Agent Skill Compiler is an API-first backend and Python SDK for collecting agent traces, storing project-scoped runs, and analyzing repeated execution patterns into candidate skills.

This repository intentionally ships no frontend. The supported deployment model is:

1. deploy this package as your tracing and analysis API
2. instrument your backend agents with the Python SDK using `base_url`, `public_key`, and `secret_key`
3. build your frontend in a separate repo against this API using `base_url` plus the project `public_key`

## Auth Model

- trusted backend writes: `public_key` + `secret_key`
- frontend reads: `public_key`
- admin/project provisioning: optional `ASC_ADMIN_TOKEN`

Never expose the `secret_key` in browser code.

## Install

```bash
pip install agent-skill-compiler
```

For local development:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Run The API

### Local Python

```bash
source .venv/bin/activate
agent-skill-compiler serve
```

### Docker

```bash
cp .env.example .env
docker compose up --build
```

Useful endpoints:

- `GET /`
- `GET /docs`
- `GET /api/healthz`
- `POST /api/admin/projects`

## Create A Project

Protect project creation if needed:

```bash
export ASC_ADMIN_TOKEN=change-me
agent-skill-compiler serve
```

Create a project and its first keypair:

```bash
curl -X POST http://localhost:8000/api/admin/projects \
  -H "Content-Type: application/json" \
  -H "X-ASC-Admin-Token: change-me" \
  -d '{
    "name": "Support API",
    "slug": "support-api",
    "key_name": "backend"
  }'
```

Example response:

```json
{
  "project": {
    "project_id": "...",
    "name": "Support API",
    "slug": "support-api",
    "created_at": "..."
  },
  "public_key": "asc_pk_...",
  "secret_key": "asc_sk_...",
  "key_name": "backend"
}
```

## Backend Usage

Recommended environment variables:

```bash
export ASC_BASE_URL=http://localhost:8000
export ASC_PUBLIC_KEY=asc_pk_your_project_public_key
export ASC_SECRET_KEY=asc_sk_your_project_secret_key
```

Minimal SDK example:

```python
from agent_skill_compiler import SkillCompilerClient

client = SkillCompilerClient(
    base_url="http://localhost:8000",
    public_key="asc_pk_your_project_public_key",
    secret_key="asc_sk_your_project_secret_key",
)

run = client.start_run(
    task_name="customer_followup",
    input_text="Review this customer issue and prepare next steps.",
    metadata={"service": "support-api", "workflow": "support_triage"},
)

tool_call = client.record_event(
    run_id=run.run_id,
    agent_name="ResearchAgent",
    action_name="search_docs",
    action_kind="tool_call",
    input_payload={"query": "latest billing escalation policy"},
)

client.record_event(
    run_id=run.run_id,
    agent_name="ResearchAgent",
    action_name="search_docs",
    action_kind="tool_result",
    output_payload={"documents": ["billing-policy-v2"]},
    latency_ms=142,
    parent_event_id=tool_call.event_id,
)

client.record_event(
    run_id=run.run_id,
    agent_name="SummaryAgent",
    action_name="final_response",
    action_kind="final_output",
    output_payload={"response": "Prepared next steps for the support team."},
    latency_ms=85,
)

client.finish_run(run_id=run.run_id, status="success")
client.close()
```

## Frontend Usage

Your separate frontend should use the `public_key` only.

Project-scoped read endpoints:

- `GET /api/runs?public_key=asc_pk_...`
- `GET /api/runs/{run_id}?public_key=asc_pk_...`
- `GET /api/skills?public_key=asc_pk_...`
- `POST /api/analyze?public_key=asc_pk_...`

## API Reference

Trusted backend writes:

- `POST /api/runs/start`
- `POST /api/runs/{run_id}/events`
- `POST /api/runs/{run_id}/finish`

Project reads:

- `GET /api/runs`
- `GET /api/runs/{run_id}`
- `GET /api/skills`
- `POST /api/analyze`

Admin and ops:

- `GET /api/healthz`
- `GET /api/config`
- `GET /api/projects`
- `GET /api/projects/{project_id}/keys`
- `POST /api/admin/projects`
- `POST /api/admin/reset`
- `POST /api/reports/generate`
- `GET /reports/latest`

Write requests must include:

- `X-ASC-Public-Key`
- `X-ASC-Secret-Key`

## Notes

- SQLite is used for local-first persistence.
- Candidate skills are heuristic suggestions derived from repeated event subsequences.
- HTML reporting remains available through the report endpoints and CLI.

## License

MIT
