⚡ ASP SDK Documentation

Complete API reference for the Open Skills Protocol (OSP) SDK. Build AI skills in 3 lines.

Installation

# Install from PyPI
pip install asp-sdk

# Or with dev tools
pip install asp-sdk[dev]
📋 Requirements Python 3.9+ · No external dependencies for core functionality

Quick Start

Create a file main.py and add:

from asp import skill, serve

@skill("greet", description="Say hello")
def greet(name: str) -> str:
    return f"Hello, {name}!"

serve()  # → localhost:8080
# Run
asp dev main.py

# Test
curl -X POST localhost:8080/asp-rpc \
  -d '{"jsonrpc":"2.0","method":"asp.route","params":{"query":"say hi to Alex"},"id":1}'

Core Concepts

How Routing Works

ASP uses a 4-stage routing pipeline to match natural language queries to skills:

Stage Engine Purpose
1. Safety Check Regex + ML Filter dangerous/malicious queries
2. BM25 Keyword Fast keyword matching against skill descriptions
3. Semantic Embeddings Deep meaning matching (optional)
4. Conflict Resolution Score fusion Pick the best candidate when multiple match

@skill Decorator

Register a function as a routable skill.

@skill(skill_id, *, description, keywords, risk_level)
def my_skill(**kwargs) -> Any: ...
Parameter Type Description
skill_id str required Unique identifier (e.g. "weather")
description str required Human-readable description for routing
keywords list[str] optional Activation keywords for BM25 matching
risk_level str optional "low" (default), "medium", "high"

Examples

@skill("calculator",
       description="Perform mathematical calculations",
       keywords=["math", "calc", "compute"],
       risk_level="low")
def calculator(expression: str) -> str:
    """Evaluate a math expression safely."""
    allowed = set("0123456789+-*/.()")
    if not all(c in allowed or c == ' ' for c in expression):
        return "Error: only basic math allowed"
    return str(eval(expression))

serve()

Start the ASP HTTP server with auto-discovery of registered skills.

serve(host="0.0.0.0", port=8080, dashboard=True)
Parameter Default Description
host "0.0.0.0" Bind address
port 8080 HTTP port
dashboard True Enable built-in dashboard at /_dashboard

ASPServer

Low-level server for programmatic control.

from asp.server import ASPServer

server = ASPServer(host="0.0.0.0", port=8080)
server.register_skill(my_skill_wrapper)
server.start()

Methods

Method Description
register_skill(wrapper) Register a SkillWrapper
start() Start HTTP server (blocking)
route(query) Route a query to the best skill
execute(skill_id, **args) Execute a skill directly
list_skills() List all registered skills

ASPClient

Connect to a running ASP server programmatically.

from asp import ASPClient

client = ASPClient("http://localhost:8080")

# Route a natural language query
result = client.route("what's the weather in Kyiv?")

# Execute a skill directly
result = client.execute("greet", name="Oleksandr")

# List all available skills
skills = client.list_skills()

CLI: asp dev

Start a development server with hot-reload.

asp dev main.py              # Start on port 8080
asp dev main.py --port 3000  # Custom port

CLI: asp init

Scaffold a new ASP project.

asp init my-project
# Creates:
#   my-project/main.py    — 2 example skills
#   my-project/README.md  — Getting started guide

CLI: asp skills

List registered skills on a running server.

asp skills                         # localhost:8080
asp skills --host http://my-server  # Remote server

Environment Variables

Variable Default Description
ASP_MODE dev dev or production
ASP_ADMIN_KEY — Admin API key for protected endpoints
ASP_PORT 8080 Server port
ASP_LOG_LEVEL info Logging: debug, info, warning, error

Routing Pipeline

The 4-stage pipeline processes each query in <1ms:

⚡ Performance Full 4-stage routing completes in under 1ms. No network calls, no LLM API, pure local intelligence. 
# Pipeline stages (automatic):
query → safety_check()   # 1. Block dangerous queries
      → bm25_match()     # 2. Keyword-based skill matching
      → semantic_rank()  # 3. Deep meaning matching
      → resolve()        # 4. Pick winner, break ties
      → result

Safety System

ASP includes a 3-layer safety system that runs before any skill execution:

Layer Engine Speed
Regex patterns Pre-compiled blocklist < 0.01ms
ML classifier Lightweight model < 0.1ms
Anomaly detection Statistical < 0.05ms
⚠️ Production Always set ASP_ADMIN_KEY in production to protect admin endpoints.


⚡ OSP — Open Skills Protocol · amadeq.org · v0.1.0