Metadata-Version: 2.4
Name: agent-skill-compiler
Version: 0.2.0
Summary: Framework-agnostic agent tracing backend and Python SDK for mining repeated execution patterns into candidate skills.
Project-URL: Homepage, https://github.com/dlamaro96/Skill-Compiler
Project-URL: Frontend, https://github.com/dlamaro96/skills-compiler
Project-URL: Issues, https://github.com/dlamaro96/Skill-Compiler/issues
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
Provides-Extra: agno
Requires-Dist: agno; extra == 'agno'
Description-Content-Type: text/markdown

# Agent Skill Compiler

Agent Skill Compiler is a framework-agnostic tracing backend and Python SDK for collecting agent runs, normalizing tool and routing events, and mining repeated execution patterns into candidate skills.

It is designed to work with:

- custom agent runtimes
- Agno
- Microsoft Agent Framework
- any Python-based framework that can call the generic tracing helpers

This package ships the backend API and SDK only. The frontend is deployed separately here:

- [skills-compiler frontend](https://github.com/dlamaro96/skills-compiler)

## Install

Core package:

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

With Agno adapter support:

```bash
pip install "agent-skill-compiler[agno]"
```

For Microsoft Agent Framework, install the framework package alongside this SDK:

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

## What You Deploy

The recommended deployment model is:

1. deploy `agent-skill-compiler` as your tracing and analysis API
2. instrument your backend agents with the SDK
3. deploy your frontend separately from [skills-compiler](https://github.com/dlamaro96/skills-compiler)

## Auth Model

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

Never expose the `secret_key` in browser code.

## Run The API

### Local Python

```bash
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

```bash
export ASC_ADMIN_TOKEN=change-me
```

```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"
}
```

## Base Client

```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"]},
    parent_event_id=tool_call.event_id,
)

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

## Generic Framework Integration

Use the generic helpers for any custom framework or homegrown orchestration layer:

```python
from agent_skill_compiler import SkillCompilerClient, trace_run

client = SkillCompilerClient(
    base_url="http://localhost:8000",
    public_key="asc_pk_...",
    secret_key="asc_sk_...",
)

with trace_run(
    client,
    task_name="ticket_triage",
    input_text="Please investigate this support issue.",
    metadata={"framework": "custom"},
) as run:
    tool_call = run.tool_call(
        agent_name="Coordinator",
        action_name="search_docs",
        arguments={"query": "refund policy"},
    )
    run.tool_result(
        agent_name="Coordinator",
        action_name="search_docs",
        result={"documents": ["refund-policy-v2"]},
        parent_event_id=tool_call.event_id,
    )
    run.final_output(
        agent_name="Responder",
        output="Escalate to billing operations.",
    )
```

## Agno Integration

Use the Agno adapter to wrap a normal `agent.run(...)` call and automatically capture tool activity through Agno tool hooks:

```python
from agno.agent import Agent
from agent_skill_compiler import SkillCompilerClient, run_agno_agent

client = SkillCompilerClient(
    base_url="http://localhost:8000",
    public_key="asc_pk_...",
    secret_key="asc_sk_...",
)

response = run_agno_agent(
    agent,
    client,
    input="Summarize the latest billing escalation guidance.",
    task_name="billing_guidance",
    metadata={"framework": "agno"},
)
```

## Microsoft Agent Framework Integration

Microsoft Agent Framework is the new successor to Semantic Kernel and AutoGen. Agent Skill Compiler integrates with it through official middleware hooks.

```python
from agent_skill_compiler import AsyncSkillCompilerClient, create_agent_framework_middleware

client = AsyncSkillCompilerClient(
    base_url="http://localhost:8000",
    public_key="asc_pk_...",
    secret_key="asc_sk_...",
)

middleware = create_agent_framework_middleware(
    client,
    task_name="weather_assistant",
    metadata={"framework": "microsoft-agent-framework"},
)

# Pass `middleware=middleware` when constructing the agent or on a specific run.
```

The adapter uses:

- agent middleware for run start and finish
- function middleware for tool call and tool result capture

## Frontend Usage

Your separate frontend should use the `public_key` only and read project-scoped data from the deployed API.

Primary frontend 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_...`

Frontend repo:

- [https://github.com/dlamaro96/skills-compiler](https://github.com/dlamaro96/skills-compiler)

## Public API

Top-level exports:

- `SkillCompilerClient`
- `AsyncSkillCompilerClient`
- `trace_run`
- `trace_run_async`
- `run_agno_agent`
- `create_agent_framework_middleware`

## 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
