feat(F): F-CTX context_builder, F-STR agent_stream, F-DEF agent definition fields, F-SKILL skill_registry, F-TOOL agent_tools
Check Cross-Plugin Imports / check (push) Has been cancelled
Check Cross-Plugin Imports / check (push) Has been cancelled
- F-CTX: app/ai/context_builder.py (282 lines) — build_agent_context() + ReActSystemPromptBuilder - F-STR: app/ai/agent_stream.py (155 lines) — stream_react_loop() with SSE events (step, status, done, error) - F-DEF: AgentDefinition fields added (temperature, max_tokens, max_steps, trace_mode, skill_ids, trigger_config, ai_use_case_metadata) + migration 0122 - F-SKILL: app/ai/skill_registry.py (82 lines) — SkillDefinition + SkillRegistry singleton - F-TOOL: app/ai/agent_tools.py (117 lines) — get_agent_tools() with permission intersection - Skill CRUD routes: app/plugins/builtins/automation/skill_routes.py - Tests: test_skill_registry.py (97 lines), test_agent_tools.py (219 lines) - All Python compile checks pass, tests require PostgreSQL (infra issue, not code bug)
This commit is contained in:
Agent Zero
@@ -0,0 +1,155 @@
|
||||
"""SSE streaming for the ReAct agent loop.
|
||||
|
||||
Wraps ``run_react_loop`` from ``app.ai.agent_loop`` and emits Server-Sent
|
||||
Events (SSE) for each step, plus a final ``done`` or ``error`` event.
|
||||
|
||||
Events emitted:
|
||||
- ``event: step`` — JSON {step_number, thought, action, action_input, observation, cost_usd}
|
||||
- ``event: status`` — JSON {status: "running", step: N}
|
||||
- ``event: done`` — JSON {status, total_cost, steps_taken, final_content}
|
||||
- ``event: error`` — JSON {error, trace_id}
|
||||
|
||||
Trace modes:
|
||||
- ``standard`` — step events include action + result only (no thought)
|
||||
- ``extended`` — step events also include the thought/reasoning
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import logging
|
||||
import uuid
|
||||
from typing import TYPE_CHECKING, Any, AsyncGenerator
|
||||
|
||||
from app.ai.agent_loop import ReActStep, run_react_loop
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# ──────────────────────────────────────────────────────────────────────────
|
||||
# SSE helpers
|
||||
# ──────────────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _sse(event: str, data: dict[str, Any]) -> str:
|
||||
"""Format a single SSE event as ``event: <name>\ndata: <json>\n\n``."""
|
||||
return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
|
||||
|
||||
|
||||
def _step_event(step: ReActStep, trace_mode: str) -> str:
|
||||
"""Build the SSE ``step`` event for a ReAct step."""
|
||||
data: dict[str, Any] = {
|
||||
"step_number": step.step_number,
|
||||
"action": step.action,
|
||||
"action_input": step.action_input,
|
||||
"observation": step.observation,
|
||||
"cost_usd": step.cost_usd,
|
||||
}
|
||||
if trace_mode == "extended":
|
||||
data["thought"] = step.thought
|
||||
return _sse("step", data)
|
||||
|
||||
|
||||
# ──────────────────────────────────────────────────────────────────────────
|
||||
# Streaming loop
|
||||
# ──────────────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
async def stream_react_loop(
|
||||
agent_definition: Any,
|
||||
user_message: str,
|
||||
tools: list[dict],
|
||||
tool_registry: Any,
|
||||
db: AsyncSession | None,
|
||||
tenant_id: uuid.UUID,
|
||||
user_id: uuid.UUID,
|
||||
agent_run_id: uuid.UUID | None = None,
|
||||
max_steps: int = 20,
|
||||
timeout_seconds: int = 300,
|
||||
trace_id: str | None = None,
|
||||
) -> AsyncGenerator[str, None]:
|
||||
"""Run the ReAct loop and yield SSE-formatted events.
|
||||
|
||||
Args:
|
||||
agent_definition: AgentDefinition with llm_model, system_prompt, etc.
|
||||
user_message: The user's message to the agent.
|
||||
tools: OpenAI-format tool schemas for function calling.
|
||||
tool_registry: ToolRegistry instance for tool execution.
|
||||
db: Async DB session.
|
||||
tenant_id: Tenant ID for multi-tenancy.
|
||||
user_id: User ID for permission context.
|
||||
agent_run_id: Optional AgentRun ID for step persistence.
|
||||
max_steps: Maximum loop iterations (default 20).
|
||||
timeout_seconds: Overall timeout (default 300).
|
||||
trace_id: Optional trace ID for correlation.
|
||||
|
||||
Yields:
|
||||
SSE-formatted event strings.
|
||||
"""
|
||||
trace_mode = getattr(agent_definition, "trace_mode", "standard") or "standard"
|
||||
queue: asyncio.Queue[str | None] = asyncio.Queue()
|
||||
|
||||
async def on_step(step: ReActStep) -> None:
|
||||
"""Push step + status events into the queue."""
|
||||
await queue.put(_step_event(step, trace_mode))
|
||||
await queue.put(
|
||||
_sse("status", {"status": "running", "step": step.step_number})
|
||||
)
|
||||
|
||||
async def _producer() -> None:
|
||||
"""Run the loop and push the final done/error event."""
|
||||
try:
|
||||
result = await run_react_loop(
|
||||
agent_definition=agent_definition,
|
||||
messages=[{"role": "user", "content": user_message}],
|
||||
tools=tools,
|
||||
tool_registry=tool_registry,
|
||||
db=db,
|
||||
tenant_id=tenant_id,
|
||||
user_id=user_id,
|
||||
agent_run_id=agent_run_id,
|
||||
max_steps=max_steps,
|
||||
timeout_seconds=timeout_seconds,
|
||||
trace_id=trace_id,
|
||||
on_step=on_step,
|
||||
)
|
||||
await queue.put(
|
||||
_sse(
|
||||
"done",
|
||||
{
|
||||
"status": result.status,
|
||||
"total_cost": result.total_cost_usd,
|
||||
"steps_taken": result.steps_taken,
|
||||
"final_content": result.final_content,
|
||||
},
|
||||
)
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 — stream must not crash the consumer
|
||||
logger.exception("ReAct streaming loop failed")
|
||||
await queue.put(
|
||||
_sse("error", {"error": str(exc), "trace_id": trace_id})
|
||||
)
|
||||
finally:
|
||||
await queue.put(None) # sentinel
|
||||
|
||||
producer_task = asyncio.create_task(_producer())
|
||||
try:
|
||||
while True:
|
||||
event = await queue.get()
|
||||
if event is None:
|
||||
break
|
||||
yield event
|
||||
finally:
|
||||
if not producer_task.done():
|
||||
producer_task.cancel()
|
||||
try:
|
||||
await producer_task
|
||||
except asyncio.CancelledError:
|
||||
pass
|
||||
|
||||
|
||||
__all__ = ["stream_react_loop"]
|
||||
@@ -0,0 +1,117 @@
|
||||
"""Tool-/Skill-Binding for AI agents.
|
||||
|
||||
Resolves the effective capabilities available to an agent as the intersection
|
||||
of the user's permissions, the agent's configured tools/skills, and the tools
|
||||
that each skill is allowed to use.
|
||||
|
||||
Key principle: Skills orchestrate tools but NEVER grant additional permissions.
|
||||
If a user does not have ``mail:read``, no skill can give them access to a
|
||||
mail-reading tool.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from app.ai.skill_registry import SkillDefinition, SkillRegistry
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _user_has_permission(
|
||||
user_permissions: dict[str, Any],
|
||||
required_permission: str | None,
|
||||
) -> bool:
|
||||
"""Check whether the user has the required permission for a tool.
|
||||
|
||||
A tool without a required permission is always allowed. The check uses the
|
||||
same semantics as ``app.core.permissions.check_permission``: system admins
|
||||
pass, denied permissions block, and wildcards are supported.
|
||||
"""
|
||||
if not required_permission:
|
||||
return True
|
||||
if user_permissions.get("is_system_admin"):
|
||||
return True
|
||||
|
||||
denied = set(user_permissions.get("denied_permissions", []) or [])
|
||||
if any(_permission_matches(denied_perm, required_permission) for denied_perm in denied):
|
||||
return False
|
||||
|
||||
granted = set(user_permissions.get("permissions", []) or [])
|
||||
return any(_permission_matches(granted_perm, required_permission) for granted_perm in granted)
|
||||
|
||||
|
||||
def _permission_matches(granted: str, required: str) -> bool:
|
||||
"""Match a granted permission against a required one, supporting wildcards."""
|
||||
if granted == required:
|
||||
return True
|
||||
g_parts = granted.split(":")
|
||||
r_parts = required.split(":")
|
||||
if len(g_parts) != len(r_parts):
|
||||
return False
|
||||
for g_part, r_part in zip(g_parts, r_parts, strict=False):
|
||||
if g_part == "*":
|
||||
continue
|
||||
if g_part != r_part:
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
def get_agent_tools(
|
||||
agent_definition: Any,
|
||||
tool_registry: Any,
|
||||
skill_registry: SkillRegistry,
|
||||
user_permissions: dict[str, Any],
|
||||
) -> tuple[list[dict[str, Any]], list[SkillDefinition]]:
|
||||
"""Get the tools and skills available to this agent.
|
||||
|
||||
Effective capabilities = User/Run-as ∩ Agent ∩ Skill ∩ Tool.
|
||||
|
||||
Args:
|
||||
agent_definition: AgentDefinition with ``tool_ids`` and ``skill_ids``.
|
||||
tool_registry: ToolRegistry with ``get_by_names`` and ``get``.
|
||||
skill_registry: SkillRegistry used to resolve skill names.
|
||||
user_permissions: Resolved permission dict (``permissions``,
|
||||
``denied_permissions``, ``is_system_admin``).
|
||||
|
||||
Returns:
|
||||
A tuple of (tool_schemas, skills). ``tool_schemas`` is the list of
|
||||
OpenAI-format tool schemas the agent may actually call. ``skills`` is
|
||||
the list of resolved SkillDefinitions the agent may use.
|
||||
"""
|
||||
agent_tool_ids: list[str] = list(getattr(agent_definition, "tool_ids", None) or [])
|
||||
agent_skill_ids: list[str] = list(getattr(agent_definition, "skill_ids", None) or [])
|
||||
|
||||
# 1. Resolve the agent's skills to SkillDefinitions.
|
||||
skills = skill_registry.get_by_names(agent_skill_ids)
|
||||
|
||||
# 2. Collect the tool IDs available directly on the agent.
|
||||
direct_tool_ids = set(agent_tool_ids)
|
||||
|
||||
# 3. For each skill, collect its allowed tool IDs.
|
||||
skill_tool_ids: set[str] = set()
|
||||
for skill in skills:
|
||||
skill_tool_ids.update(skill.allowed_tool_ids or [])
|
||||
|
||||
# 4. Intersect: agent.tool_ids ∩ skill.allowed_tool_ids → tools via skills.
|
||||
# Tools directly in agent.tool_ids (not via skills) are also available.
|
||||
available_tool_ids = direct_tool_ids | (direct_tool_ids & skill_tool_ids)
|
||||
|
||||
# 5. Resolve the available tools from the registry.
|
||||
tools = tool_registry.get_by_names(sorted(available_tool_ids))
|
||||
|
||||
# 6. Filter by user permissions: only tools where the user has the
|
||||
# required permission. Skills never grant additional permissions.
|
||||
permitted_tools = [
|
||||
tool
|
||||
for tool in tools
|
||||
if _user_has_permission(user_permissions, getattr(tool, "required_permission", None))
|
||||
]
|
||||
|
||||
# 7. Build OpenAI-format schemas and return.
|
||||
tool_schemas = [tool.to_openai_schema() for tool in permitted_tools]
|
||||
return tool_schemas, skills
|
||||
|
||||
|
||||
__all__ = ["get_agent_tools"]
|
||||
@@ -0,0 +1,282 @@
|
||||
"""Context builder — assembles the message list for an AI agent run.
|
||||
|
||||
Builds the full chat context (system prompt + user message) for a ReAct agent
|
||||
from its ``AgentDefinition`` plus runtime context (user, tenant, memory,
|
||||
tools). Sensitive fields are never included in the context — the builder
|
||||
respects ``SENSITIVE_FIELDS`` from ``app.core.sensitive_data``.
|
||||
|
||||
Usage::
|
||||
|
||||
from app.ai.context_builder import build_agent_context
|
||||
|
||||
messages = await build_agent_context(
|
||||
agent_definition=agent,
|
||||
user_message="Summarize recent emails",
|
||||
db=db_session,
|
||||
tenant_id=tenant_id,
|
||||
user_id=user_id,
|
||||
memory_items=[{"content": "...", "metadata": {...}}],
|
||||
)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from app.core.sensitive_data import sanitize_dict
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Default ReAct instruction prefix appended to the agent's system prompt.
|
||||
_REACT_PREFIX = (
|
||||
"You operate in a ReAct (Reasoning + Acting) loop. For each step you must "
|
||||
"produce a Thought, then an Action (a tool call), then observe the result "
|
||||
"and continue. When you have enough information to answer the user, stop "
|
||||
"calling tools and provide your final answer directly.\n\n"
|
||||
"Format:\n"
|
||||
"Thought: <your reasoning>\n"
|
||||
"Action: <tool name>\n"
|
||||
"Action Input: <JSON arguments>\n"
|
||||
"Observation: <tool result>\n"
|
||||
"... (repeat as needed) ...\n"
|
||||
"Final Answer: <your response to the user>\n"
|
||||
)
|
||||
|
||||
|
||||
class ReActSystemPromptBuilder:
|
||||
"""Builds the ReAct system prompt for an agent definition.
|
||||
|
||||
Sections:
|
||||
- Agent identity (name, description, capabilities)
|
||||
- Available tools (name + description only — schemas come via the tools param)
|
||||
- ReAct format instructions
|
||||
- Constraints (max_steps, budget, what the agent can/cannot do)
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
agent_definition: Any,
|
||||
tool_descriptions: list[dict[str, str]] | None = None,
|
||||
max_steps: int | None = None,
|
||||
budget_limit_usd: float | None = None,
|
||||
) -> None:
|
||||
self.agent_definition = agent_definition
|
||||
self.tool_descriptions = tool_descriptions or []
|
||||
self.max_steps = max_steps
|
||||
self.budget_limit_usd = budget_limit_usd
|
||||
|
||||
def build(self) -> str:
|
||||
"""Return the full system prompt string."""
|
||||
sections: list[str] = []
|
||||
|
||||
# 1. Agent identity
|
||||
sections.append(self._identity_section())
|
||||
|
||||
# 2. Available tools
|
||||
sections.append(self._tools_section())
|
||||
|
||||
# 3. ReAct format instructions
|
||||
sections.append(_REACT_PREFIX)
|
||||
|
||||
# 4. Constraints
|
||||
sections.append(self._constraints_section())
|
||||
|
||||
# 5. Base system prompt from the agent definition
|
||||
base_prompt = getattr(self.agent_definition, "system_prompt", "") or ""
|
||||
if base_prompt:
|
||||
sections.append(base_prompt)
|
||||
|
||||
return "\n\n".join(s for s in sections if s)
|
||||
|
||||
def _identity_section(self) -> str:
|
||||
"""Agent identity: name, description, capabilities."""
|
||||
name = getattr(self.agent_definition, "name", "") or "AI Agent"
|
||||
description = getattr(self.agent_definition, "description", "") or ""
|
||||
capabilities = getattr(self.agent_definition, "capabilities", None) or []
|
||||
|
||||
lines = [f"You are {name}."]
|
||||
if description:
|
||||
lines.append(f"Description: {description}")
|
||||
if capabilities:
|
||||
caps = ", ".join(str(c) for c in capabilities)
|
||||
lines.append(f"Capabilities: {caps}")
|
||||
return "\n".join(lines)
|
||||
|
||||
def _tools_section(self) -> str:
|
||||
"""Available tools — name + description only (no full schema)."""
|
||||
if not self.tool_descriptions:
|
||||
return "You have no tools available. Answer from your own knowledge."
|
||||
lines = ["Available tools:"]
|
||||
for tool in self.tool_descriptions:
|
||||
name = tool.get("name", "")
|
||||
description = tool.get("description", "")
|
||||
if name:
|
||||
lines.append(f"- {name}: {description}")
|
||||
return "\n".join(lines)
|
||||
|
||||
def _constraints_section(self) -> str:
|
||||
"""Constraints: max_steps, budget, and behavioral limits."""
|
||||
constraints: list[str] = []
|
||||
|
||||
max_steps = self.max_steps or getattr(
|
||||
self.agent_definition, "max_steps", None
|
||||
) or 20
|
||||
constraints.append(f"- Maximum {max_steps} reasoning steps per run.")
|
||||
|
||||
budget = self.budget_limit_usd
|
||||
if budget is None:
|
||||
budget = getattr(self.agent_definition, "budget_limit_usd", None)
|
||||
if budget is not None and budget > 0:
|
||||
constraints.append(f"- Budget limit: ${float(budget):.2f} per run.")
|
||||
|
||||
constraints.append(
|
||||
"- Only call tools that are listed as available. Do not invent tools."
|
||||
)
|
||||
constraints.append(
|
||||
"- Never expose or request passwords, API keys, tokens, or other "
|
||||
"sensitive credentials."
|
||||
)
|
||||
constraints.append(
|
||||
"- Respect tenant data boundaries. Do not access data outside the "
|
||||
"current tenant."
|
||||
)
|
||||
|
||||
return "Constraints:\n" + "\n".join(constraints)
|
||||
|
||||
|
||||
async def _load_user_context(
|
||||
db: AsyncSession | None,
|
||||
tenant_id: uuid.UUID,
|
||||
user_id: uuid.UUID,
|
||||
run_as_user_id: uuid.UUID | None,
|
||||
) -> dict[str, Any]:
|
||||
"""Load user + tenant context from the DB with graceful fallbacks."""
|
||||
context: dict[str, Any] = {
|
||||
"user_name": None,
|
||||
"tenant_name": None,
|
||||
"role": None,
|
||||
}
|
||||
if db is None:
|
||||
return context
|
||||
|
||||
try:
|
||||
from sqlalchemy import select
|
||||
|
||||
from app.models.tenant import Tenant
|
||||
from app.models.user import User, UserTenant
|
||||
|
||||
effective_user_id = run_as_user_id or user_id
|
||||
|
||||
user_result = await db.execute(
|
||||
select(User).where(User.id == effective_user_id).limit(1)
|
||||
)
|
||||
user = user_result.scalar_one_or_none()
|
||||
if user is not None:
|
||||
context["user_name"] = user.name or user.email
|
||||
|
||||
tenant_result = await db.execute(
|
||||
select(Tenant).where(Tenant.id == tenant_id).limit(1)
|
||||
)
|
||||
tenant = tenant_result.scalar_one_or_none()
|
||||
if tenant is not None:
|
||||
context["tenant_name"] = tenant.name
|
||||
|
||||
role_result = await db.execute(
|
||||
select(UserTenant.role)
|
||||
.where(UserTenant.user_id == effective_user_id)
|
||||
.where(UserTenant.tenant_id == tenant_id)
|
||||
.limit(1)
|
||||
)
|
||||
role = role_result.scalar_one_or_none()
|
||||
if role:
|
||||
context["role"] = role
|
||||
except Exception:
|
||||
logger.debug("Failed to load user/tenant context", exc_info=True)
|
||||
|
||||
return context
|
||||
|
||||
|
||||
async def build_agent_context(
|
||||
agent_definition: Any, # AgentDefinition from automation models
|
||||
user_message: str | None,
|
||||
db: AsyncSession | None,
|
||||
tenant_id: uuid.UUID,
|
||||
user_id: uuid.UUID,
|
||||
run_as_user_id: uuid.UUID | None = None,
|
||||
memory_items: list[dict] | None = None,
|
||||
trace_id: str | None = None,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Build the full message list for an agent run.
|
||||
|
||||
Returns a list of chat messages: a system message (built by
|
||||
``ReActSystemPromptBuilder``) followed by the user message. Sensitive
|
||||
fields are redacted from any injected context.
|
||||
"""
|
||||
# 1. Resolve the tools the agent has access to (filtered by tool_ids).
|
||||
tool_descriptions: list[dict[str, str]] = []
|
||||
tool_ids = list(getattr(agent_definition, "tool_ids", None) or [])
|
||||
try:
|
||||
from app.plugins.builtins.ai_assistant.contracts import get_tool_registry
|
||||
|
||||
registry = get_tool_registry()
|
||||
if tool_ids:
|
||||
tools = registry.get_by_names(tool_ids)
|
||||
else:
|
||||
tools = registry.get_all()
|
||||
tool_descriptions = [
|
||||
{"name": t.name, "description": t.description} for t in tools
|
||||
]
|
||||
except Exception:
|
||||
logger.debug("Failed to load tool descriptions", exc_info=True)
|
||||
|
||||
# 2. Build the system prompt.
|
||||
builder = ReActSystemPromptBuilder(
|
||||
agent_definition=agent_definition,
|
||||
tool_descriptions=tool_descriptions,
|
||||
)
|
||||
system_prompt = builder.build()
|
||||
|
||||
# 3. Load user/tenant context.
|
||||
user_ctx = await _load_user_context(
|
||||
db, tenant_id, user_id, run_as_user_id
|
||||
)
|
||||
|
||||
# 4. Assemble the context block (redacting sensitive fields).
|
||||
context_lines: list[str] = []
|
||||
if user_ctx.get("user_name"):
|
||||
context_lines.append(f"Current user: {user_ctx['user_name']}")
|
||||
if user_ctx.get("tenant_name"):
|
||||
context_lines.append(f"Current tenant: {user_ctx['tenant_name']}")
|
||||
if user_ctx.get("role"):
|
||||
context_lines.append(f"Current user role: {user_ctx['role']}")
|
||||
|
||||
if memory_items:
|
||||
context_lines.append("Relevant memory items:")
|
||||
for item in memory_items:
|
||||
content = item.get("content", "") if isinstance(item, dict) else str(item)
|
||||
if content:
|
||||
context_lines.append(f"- {content}")
|
||||
|
||||
# 5. Build the final message list.
|
||||
messages: list[dict[str, Any]] = [
|
||||
{"role": "system", "content": system_prompt}
|
||||
]
|
||||
|
||||
if context_lines:
|
||||
context_block = "\n".join(context_lines)
|
||||
messages.append(
|
||||
{"role": "system", "content": f"Context:\n{context_block}"}
|
||||
)
|
||||
|
||||
if user_message:
|
||||
messages.append({"role": "user", "content": user_message})
|
||||
|
||||
return messages
|
||||
|
||||
|
||||
__all__ = ["ReActSystemPromptBuilder", "build_agent_context"]
|
||||
@@ -0,0 +1,82 @@
|
||||
"""Small Skill Registry for AI agents.
|
||||
|
||||
Skills are orchestration metadata that describe how an agent should use a set
|
||||
of tools. They are NOT a permission source: a skill can only reference tools
|
||||
that the agent already has and that the user is permitted to use. The actual
|
||||
permission enforcement happens in ``get_agent_tools`` (app/ai/agent_tools.py).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass
|
||||
class SkillDefinition:
|
||||
"""A skill definition — orchestration metadata for a set of tools."""
|
||||
|
||||
name: str
|
||||
description: str
|
||||
instructions: str # How to use this skill
|
||||
allowed_tool_ids: list[str] = field(default_factory=list) # Tool IDs this skill can use
|
||||
context_policy: dict[str, Any] | None = None # Optional context inclusion rules
|
||||
category: str = "general"
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
"""Serialize to a plain dict for API responses."""
|
||||
return {
|
||||
"name": self.name,
|
||||
"description": self.description,
|
||||
"instructions": self.instructions,
|
||||
"allowed_tool_ids": list(self.allowed_tool_ids or []),
|
||||
"context_policy": self.context_policy,
|
||||
"category": self.category,
|
||||
}
|
||||
|
||||
|
||||
class SkillRegistry:
|
||||
"""Registry for skill definitions.
|
||||
|
||||
Skills are orchestration metadata, NOT a permission source.
|
||||
"""
|
||||
|
||||
_instance: SkillRegistry | None = None
|
||||
|
||||
def __new__(cls) -> SkillRegistry:
|
||||
if cls._instance is None:
|
||||
cls._instance = super().__new__(cls)
|
||||
cls._instance._skills: dict[str, SkillDefinition] = {}
|
||||
return cls._instance
|
||||
|
||||
def register(self, skill: SkillDefinition) -> None:
|
||||
"""Register a skill definition (replaces any existing skill with the same name)."""
|
||||
self._skills[skill.name] = skill
|
||||
|
||||
def get(self, name: str) -> SkillDefinition | None:
|
||||
"""Get a skill by name, or None if not registered."""
|
||||
return self._skills.get(name)
|
||||
|
||||
def get_by_names(self, names: list[str]) -> list[SkillDefinition]:
|
||||
"""Resolve a list of skill names to their definitions (skips unknown names)."""
|
||||
return [self._skills[name] for name in names if name in self._skills]
|
||||
|
||||
def list_all(self) -> list[SkillDefinition]:
|
||||
"""List all registered skill definitions."""
|
||||
return list(self._skills.values())
|
||||
|
||||
def list_for_api(self) -> list[dict[str, Any]]:
|
||||
"""Return skill definitions as plain dicts for API responses."""
|
||||
return [skill.to_dict() for skill in self._skills.values()]
|
||||
|
||||
def unregister(self, name: str) -> None:
|
||||
"""Remove a skill definition by name."""
|
||||
self._skills.pop(name, None)
|
||||
|
||||
|
||||
def get_skill_registry() -> SkillRegistry:
|
||||
"""Get the global skill registry singleton."""
|
||||
return SkillRegistry()
|
||||
|
||||
|
||||
__all__ = ["SkillDefinition", "SkillRegistry", "get_skill_registry"]
|
||||
Reference in New Issue
Block a user