Metadata-Version: 2.4
Name: asterskills
Version: 1.0.0
Summary: Universal skills loader for AI agent frameworks with progressive disclosure
Project-URL: Homepage, https://joinasterism.com
Project-URL: Documentation, https://joinasterism.com/docs
Project-URL: Repository, https://github.com/joinasterism/ask
Project-URL: Issues, https://github.com/joinasterism/ask/issues
Author-email: asterskills <support@joinasterism.com>
License-Expression: MIT
Keywords: agents,ai,autogen,claude,crewai,langchain,langgraph,mcp,skills
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: crewai>=0.1.0; extra == 'all'
Requires-Dist: langchain-core>=0.1.0; extra == 'all'
Requires-Dist: langchain>=0.1.0; extra == 'all'
Requires-Dist: pyautogen>=0.2.0; extra == 'all'
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2.0; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai>=0.1.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Requires-Dist: langchain>=0.1.0; extra == 'langchain'
Description-Content-Type: text/markdown

# asterskills

> Universal skills loader for AI agent frameworks with progressive disclosure

[![PyPI version](https://badge.fury.io/py/asterskills.svg)](https://pypi.org/project/asterskills/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

The official Python SDK for the [ask](https://joinasterism.com) skills registry. Load AI agent skills into any framework with progressive disclosure support.

## Features

- **Progressive Disclosure**: Load skills at different levels (metadata, contract, summary, full)
- **Framework Adapters**: Ready-to-use integrations for LangChain, CrewAI, AutoGen, Semantic Kernel
- **Type-Safe**: Full type hints and Pydantic models
- **Async-First**: Built on httpx for async HTTP
- **Smart Caching**: Automatic caching with configurable TTL
- **Token Budget**: Load skills within context budget constraints

## Installation

```bash
pip install asterskills

# With framework adapters
pip install asterskills[langchain]
pip install asterskills[crewai]
pip install asterskills[autogen]
pip install asterskills[all]  # All adapters
```

## Quick Start

```python
from asterskills import SkillsLoader, LoadLevel

# Create a loader
loader = SkillsLoader()

# Load a skill with full content
skill = await loader.load("pdf-tools")
print(skill.metadata.name)  # 'pdf-tools'
print(skill.metadata.version)  # '2.1.0'

# Progressive disclosure - load only what you need
metadata = await loader.load("pdf-tools", level=LoadLevel.METADATA)  # ~50 tokens
contract = await loader.load("pdf-tools", level=LoadLevel.CONTRACT)  # ~300 tokens
summary = await loader.load("pdf-tools", level=LoadLevel.SUMMARY)    # ~500 tokens
full = await loader.load("pdf-tools", level=LoadLevel.FULL)          # Full content

# Load within a token budget
skill = await loader.load_with_budget("pdf-tools", max_tokens=500)
```

## Framework Adapters

### LangChain / LangGraph

```python
from asterskills.adapters import AsterSkillTool, AsterToolkit
from langgraph.prebuilt import create_react_agent

# Single tool
pdf_tool = await AsterSkillTool.from_skill("pdf-tools")
agent = create_react_agent(model, tools=[pdf_tool])

# Multiple tools from search
toolkit = await AsterToolkit.from_search("code generation", limit=5)
agent = create_react_agent(model, tools=toolkit.get_tools())

# From category
toolkit = await AsterToolkit.from_category("testing", limit=10)
```

### CrewAI

```python
from crewai import Agent, Task, Crew
from asterskills.adapters import AsterCrewTool, create_crewai_tools

# Create tools
pdf_tool = await AsterCrewTool.from_skill("pdf-tools")
git_tool = await AsterCrewTool.from_skill("git-commit")

# Use in agent
researcher = Agent(
    role="Document Analyst",
    goal="Extract and analyze document contents",
    tools=[pdf_tool, git_tool],
    llm=llm
)
```

### AutoGen

```python
from autogen import AssistantAgent, UserProxyAgent
from asterskills.adapters import register_aster_skills

# Register skills with agent
assistant = AssistantAgent("assistant", llm_config=llm_config)
await register_aster_skills(
    assistant,
    skills=["pdf-tools", "git-commit", "code-review"],
)

# Skills are now available as functions
user_proxy = UserProxyAgent("user_proxy")
user_proxy.initiate_chat(assistant, message="Extract text from report.pdf")
```

### Semantic Kernel

```python
from semantic_kernel import Kernel
from asterskills.adapters import register_aster_plugin

kernel = Kernel()

# Register as plugin
await register_aster_plugin(kernel, "pdf-tools")

# Use in prompts
result = await kernel.invoke_prompt(
    "Extract the summary from {{$file_path}}",
    file_path="report.pdf"
)
```

## Configuration

```python
from asterskills import SkillsLoader, LoaderConfig

loader = SkillsLoader(LoaderConfig(
    api_key="aster_live_xxx",        # For private skills
    base_url="https://api.joinasterism.com/v1",  # Custom registry
    cache_ttl=3600,                # Cache duration in seconds
    debug=True,                    # Enable debug logging
    timeout=30.0,                  # Request timeout
))
```

## Skill Execution

Execute skills in the hosted runtime:

```python
# Synchronous execution
result = await loader.execute("pdf-tools", {
    "file_path": "document.pdf",
    "extract": "text"
})
print(result.outputs)  # {'text': '...', 'pages': 5}

# Async execution
result = await loader.execute("pdf-tools", {"file_path": "large.pdf"}, async_=True)
print(result.execution_id)  # 'exec-abc123'

# Check status
status = await loader.get_execution_status(result.execution_id)
print(status.status)  # 'completed'
```

## Search and Discovery

```python
# Search for skills
results = await loader.search("code generation", limit=10)
for skill in results:
    print(f"{skill.full_name}: {skill.description}")

# List by category
skills = await loader.list(category="testing", sort="downloads", limit=20)
```

## Type Definitions

The SDK provides full type definitions for all skill components:

```python
from asterskills import (
    LoadLevel,
    LoaderConfig,
    SkillMetadata,
    SkillContract,
    SkillParameter,
    CapabilityDeclaration,
    LoadedSkill,
    ToolDefinition,
    ExecuteResult,
)
```

## API Reference

### SkillsLoader

| Method                               | Description                              |
| ------------------------------------ | ---------------------------------------- |
| `load(name, level, version)`         | Load a skill with progressive disclosure |
| `load_with_budget(name, max_tokens)` | Load within token budget                 |
| `search(query, limit)`               | Search for skills                        |
| `list(sort, limit, category)`        | List popular skills                      |
| `execute(name, inputs, async_)`      | Execute in hosted runtime                |
| `get_execution_status(id)`           | Check execution status                   |
| `clear_cache()`                      | Clear skill cache                        |

### LoadLevel

| Level      | Description                     | ~Tokens  |
| ---------- | ------------------------------- | -------- |
| `METADATA` | Name, version, description      | ~50      |
| `CONTRACT` | + inputs, outputs, capabilities | ~300     |
| `SUMMARY`  | + first section                 | ~500     |
| `FULL`     | Complete skill content          | Variable |

## License

MIT
