Tool registry models for CrewMaster v2.0.0.
| MODULE | DESCRIPTION |
|---|---|
models |
Tool and capability models for CrewMaster v2.0.0. |
models_test |
Tests for ToolSchema and Capability models. |
registry |
ToolRegistry for CrewMaster v2.0.0. |
registry_test |
Tests for ToolRegistry. |
request_capability |
Request Capability system tool for CrewMaster v2.0.0. |
request_capability_test |
Tests for the request_capability progressive disclosure system. |
| CLASS | DESCRIPTION |
|---|---|
Capability |
A registered capability that can be retrieved dynamically by agents. |
ToolSchema |
Schema describing a tool that an agent can invoke at runtime. |
ToolRegistry |
Registry of tools and capabilities, scoped by namespace. |
| FUNCTION | DESCRIPTION |
|---|---|
extract_request_capability_call |
Extract a |
get_request_capability_tool |
Return the ToolSchema for the request_capability system tool. |
is_request_capability_tool |
Check whether a tool object is the request_capability system tool. |
| ATTRIBUTE | DESCRIPTION |
|---|---|
REQUEST_CAPABILITY_NAME |
TYPE:
|
module-attribute
¤
__all__ = ['ToolSchema', 'Capability', 'ToolRegistry', 'REQUEST_CAPABILITY_NAME', 'extract_request_capability_call', 'get_request_capability_tool', 'is_request_capability_tool']
A registered capability that can be retrieved dynamically by agents.
A Capability wraps a ToolSchema with additional metadata for the SkillWeaver-style request_capability mechanism.
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Unique capability name used for registration and retrieval.
TYPE:
|
description |
Human-readable description for the SAD vocabulary bridge.
TYPE:
|
tool_schema |
The ToolSchema describing the tool's interface.
TYPE:
|
class-attribute
instance-attribute
¤
tool_schema: ToolSchema = Field(default_factory=lambda: ToolSchema(name=''))
Schema describing a tool that an agent can invoke at runtime.
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Unique tool name within the agent's toolset.
TYPE:
|
description |
Human-readable description of what the tool does.
TYPE:
|
input_schema |
JSON Schema dict describing the tool's input parameters. |
ToolRegistry()
Registry of tools and capabilities, scoped by namespace.
Tools are registered under a scope string (e.g. "code_review",
"analysis"). Retrieval by scope returns all tool schemas
registered under that scope. A global "*" scope catches every
query.
In Phase 1 this is a simple in-memory dict. The SAD vocabulary
bridge for request_capability will be added in Phase 2.
Usage::
registry = ToolRegistry()
registry.register("analysis", ToolSchema(name="search", ...))
tools = registry.retrieve("analysis") # -> [ToolSchema, ...]
| METHOD | DESCRIPTION |
|---|---|
register |
Register a tool or capability under a scope. |
retrieve_by_description |
Retrieve capabilities matching a natural-language description. |
retrieve |
Retrieve all tool schemas visible under a scope. |
register(scope: str, tool_or_capability: ToolSchema | Capability) -> None
Register a tool or capability under a scope.
| PARAMETER | DESCRIPTION |
|---|---|
|
A namespace string (e.g.
TYPE:
|
|
A ToolSchema or Capability instance.
TYPE:
|
retrieve_by_description(description: str, k: int = 5) -> list[Capability]
Retrieve capabilities matching a natural-language description.
Uses a SAD vocabulary bridge (partial keyword overlap + text matching) to score every registered Capability against the query description. Returns the top k matches by score, excluding any that score 0.0.
The search spans all scopes — every Capability ever registered is considered.
This is the runtime / semantic retrieval path (different from
retrieve() which is the plan-construction / deterministic
path).
| PARAMETER | DESCRIPTION |
|---|---|
|
Natural-language description of what the agent needs.
TYPE:
|
|
Maximum number of capabilities to return.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Capability]
|
A list of Capability instances, sorted by relevance |
list[Capability]
|
(highest score first), up to k items. |
retrieve(scope: str) -> list[ToolSchema]
Retrieve all tool schemas visible under a scope.
Returns tools registered under scope plus tools registered
under the global "*" scope. Deduplicates by name — if a
tool is registered both as raw ToolSchema and via Capability,
only one copy is returned.
| PARAMETER | DESCRIPTION |
|---|---|
|
The scope to query.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[ToolSchema]
|
A (possibly empty) list of ToolSchema instances. |
Extract a request_capability tool call from raw LLM messages.
Searches through raw_messages for an assistant message containing
a tool_calls entry where one of the calls targets
request_capability. Returns a dict with id and description
fields, or None if no request_capability call is found.
| PARAMETER | DESCRIPTION |
|---|---|
|
List of raw message dicts from the LLM provider. |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | None
|
A dict with keys |
get_request_capability_tool() -> ToolSchema
Return the ToolSchema for the request_capability system tool.
| RETURNS | DESCRIPTION |
|---|---|
ToolSchema
|
A ToolSchema describing the request_capability tool interface. |
Tool and capability models for CrewMaster v2.0.0.
| CLASS | DESCRIPTION |
|---|---|
ToolSchema |
Schema describing a tool that an agent can invoke at runtime. |
Capability |
A registered capability that can be retrieved dynamically by agents. |
Schema describing a tool that an agent can invoke at runtime.
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Unique tool name within the agent's toolset.
TYPE:
|
description |
Human-readable description of what the tool does.
TYPE:
|
input_schema |
JSON Schema dict describing the tool's input parameters. |
A registered capability that can be retrieved dynamically by agents.
A Capability wraps a ToolSchema with additional metadata for the SkillWeaver-style request_capability mechanism.
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Unique capability name used for registration and retrieval.
TYPE:
|
description |
Human-readable description for the SAD vocabulary bridge.
TYPE:
|
tool_schema |
The ToolSchema describing the tool's interface.
TYPE:
|
class-attribute
instance-attribute
¤
tool_schema: ToolSchema = Field(default_factory=lambda: ToolSchema(name=''))
Tests for ToolSchema and Capability models.
| CLASS | DESCRIPTION |
|---|---|
TestToolSchema |
|
TestCapability |
|
| METHOD | DESCRIPTION |
|---|---|
test_defaults |
ToolSchema should have sensible defaults for optional fields. |
test_full_construction |
ToolSchema should accept all fields. |
test_name_is_required |
ToolSchema should require a name. |
test_serialization_roundtrip |
ToolSchema should serialize and deserialize correctly. |
test_serialization_roundtrip()
ToolSchema should serialize and deserialize correctly.
| METHOD | DESCRIPTION |
|---|---|
test_defaults |
Capability should default to an empty ToolSchema. |
test_full_construction |
Capability should accept a full ToolSchema. |
test_name_is_required |
Capability should require a name. |
test_serialization_roundtrip |
Capability should serialize and deserialize with nested ToolSchema. |
test_serialization_roundtrip()
Capability should serialize and deserialize with nested ToolSchema.
ToolRegistry for CrewMaster v2.0.0.
The ToolRegistry stores tool schemas scoped by namespace and provides
retrieval by scope string. In Phase 2 it adds retrieve_by_description
for SAD vocabulary-bridge semantics (partial keyword overlap).
| CLASS | DESCRIPTION |
|---|---|
ToolRegistry |
Registry of tools and capabilities, scoped by namespace. |
ToolRegistry()
Registry of tools and capabilities, scoped by namespace.
Tools are registered under a scope string (e.g. "code_review",
"analysis"). Retrieval by scope returns all tool schemas
registered under that scope. A global "*" scope catches every
query.
In Phase 1 this is a simple in-memory dict. The SAD vocabulary
bridge for request_capability will be added in Phase 2.
Usage::
registry = ToolRegistry()
registry.register("analysis", ToolSchema(name="search", ...))
tools = registry.retrieve("analysis") # -> [ToolSchema, ...]
| METHOD | DESCRIPTION |
|---|---|
register |
Register a tool or capability under a scope. |
retrieve_by_description |
Retrieve capabilities matching a natural-language description. |
retrieve |
Retrieve all tool schemas visible under a scope. |
register(scope: str, tool_or_capability: ToolSchema | Capability) -> None
Register a tool or capability under a scope.
| PARAMETER | DESCRIPTION |
|---|---|
|
A namespace string (e.g.
TYPE:
|
|
A ToolSchema or Capability instance.
TYPE:
|
retrieve_by_description(description: str, k: int = 5) -> list[Capability]
Retrieve capabilities matching a natural-language description.
Uses a SAD vocabulary bridge (partial keyword overlap + text matching) to score every registered Capability against the query description. Returns the top k matches by score, excluding any that score 0.0.
The search spans all scopes — every Capability ever registered is considered.
This is the runtime / semantic retrieval path (different from
retrieve() which is the plan-construction / deterministic
path).
| PARAMETER | DESCRIPTION |
|---|---|
|
Natural-language description of what the agent needs.
TYPE:
|
|
Maximum number of capabilities to return.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Capability]
|
A list of Capability instances, sorted by relevance |
list[Capability]
|
(highest score first), up to k items. |
retrieve(scope: str) -> list[ToolSchema]
Retrieve all tool schemas visible under a scope.
Returns tools registered under scope plus tools registered
under the global "*" scope. Deduplicates by name — if a
tool is registered both as raw ToolSchema and via Capability,
only one copy is returned.
| PARAMETER | DESCRIPTION |
|---|---|
|
The scope to query.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[ToolSchema]
|
A (possibly empty) list of ToolSchema instances. |
Tests for ToolRegistry.
| CLASS | DESCRIPTION |
|---|---|
TestToolRegistry |
Tests for ToolRegistry registration and retrieval. |
Tests for ToolRegistry registration and retrieval.
| METHOD | DESCRIPTION |
|---|---|
test_register_and_retrieve_single_tool |
Register a tool and retrieve it by scope. |
test_retrieve_scope_miss_returns_empty |
Retrieving an unregistered scope returns empty list. |
test_global_scope_visible_to_all |
Tools registered under '*' should be visible to any scope. |
test_scope_specific_not_visible_to_others |
Tools registered under one scope should not leak to others. |
test_multiple_tools_same_scope |
Multiple tools under the same scope should all be returned. |
test_global_plus_scope_specific |
Scope retrieval should return both global and scope-specific tools. |
test_retrieve_star_scope_returns_only_global |
Retrieving '*' scope should return only global tools. |
test_register_capability |
Registering a Capability should make its tool_schema retrievable. |
test_register_and_retrieve_multiple_scopes |
Different scopes should have independent tool sets. |
test_register_and_retrieve_single_tool()
Register a tool and retrieve it by scope.
test_retrieve_scope_miss_returns_empty()
Retrieving an unregistered scope returns empty list.
test_global_scope_visible_to_all()
Tools registered under '*' should be visible to any scope.
test_scope_specific_not_visible_to_others()
Tools registered under one scope should not leak to others.
test_multiple_tools_same_scope()
Multiple tools under the same scope should all be returned.
test_global_plus_scope_specific()
Scope retrieval should return both global and scope-specific tools.
test_retrieve_star_scope_returns_only_global()
Retrieving '*' scope should return only global tools.
test_register_capability()
Registering a Capability should make its tool_schema retrievable.
test_register_and_retrieve_multiple_scopes()
Different scopes should have independent tool sets.
Request Capability system tool for CrewMaster v2.0.0.
Provides the request_capability system tool that enables progressive
disclosure: agents can request new capabilities at runtime by describing
what they need in natural language. CrewMaster intercepts the tool call,
queries the ToolRegistry via the SAD vocabulary bridge, expands the
agent's toolset, and re-dispatches execution.
Usage::
from crewmaster.tools.request_capability import (
REQUEST_CAPABILITY_NAME,
get_request_capability_tool,
extract_request_capability_call,
is_request_capability_tool,
)
| FUNCTION | DESCRIPTION |
|---|---|
get_request_capability_tool |
Return the ToolSchema for the request_capability system tool. |
is_request_capability_tool |
Check whether a tool object is the request_capability system tool. |
extract_request_capability_call |
Extract a |
score_capability |
Score a capability's description against query tokens. |
| ATTRIBUTE | DESCRIPTION |
|---|---|
REQUEST_CAPABILITY_NAME |
TYPE:
|
REQUEST_CAPABILITY_DESCRIPTION |
TYPE:
|
REQUEST_CAPABILITY_INPUT_SCHEMA |
|
module-attribute
¤
REQUEST_CAPABILITY_DESCRIPTION: str = 'Request access to new tools or capabilities that are not currently available in your toolset. Describe what you need in natural language and the system will search for matching capabilities. Use this when you need functionality that your current tools do not provide.'
module-attribute
¤
REQUEST_CAPABILITY_INPUT_SCHEMA: dict[str, Any] = {'type': 'object', 'properties': {'description': {'type': 'string', 'description': 'A natural language description of the capability or tool you need. Be specific about what you want to accomplish.'}}, 'required': ['description']}
get_request_capability_tool() -> ToolSchema
Return the ToolSchema for the request_capability system tool.
| RETURNS | DESCRIPTION |
|---|---|
ToolSchema
|
A ToolSchema describing the request_capability tool interface. |
Extract a request_capability tool call from raw LLM messages.
Searches through raw_messages for an assistant message containing
a tool_calls entry where one of the calls targets
request_capability. Returns a dict with id and description
fields, or None if no request_capability call is found.
| PARAMETER | DESCRIPTION |
|---|---|
|
List of raw message dicts from the LLM provider. |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | None
|
A dict with keys |
score_capability(query_tokens: list[str], capability_description: str) -> float
Score a capability's description against query tokens.
Uses partial keyword overlap: for each query token, checks if it is a substring of any word in the capability's description. Returns a score between 0.0 and 1.0 representing the fraction of query tokens that match.
| PARAMETER | DESCRIPTION |
|---|---|
|
Tokenized query words. |
|
The capability's description text.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float
|
A float score between 0.0 (no match) and 1.0 (all match). |
Tests for the request_capability progressive disclosure system.
Covers: - retrieve_by_description text matching in ToolRegistry - request_capability tool schema generation - extract_request_capability_call from raw messages - is_request_capability_tool detection - execute() with max_retrieval_rounds=1: agent calls rc, gets new tools - execute() with max_retrieval_rounds=2: two consecutive rc calls - execute() with max_retrieval_rounds=2: third call unavailable - execute() with max_retrieval_rounds=0: rc tool not in toolset - Synthetic "Now available:" message in history - Round counter behavior
| CLASS | DESCRIPTION |
|---|---|
AnalysisResult |
|
DesignResult |
|
TestRequestCapabilityTool |
Tests for get_request_capability_tool and is_request_capability_tool. |
TestExtractRequestCapabilityCall |
Tests for extract_request_capability_call. |
TestTokenize |
Tests for the _tokenize helper. |
TestScoreCapability |
Tests for score_capability. |
TestRetrieveByDescription |
Tests for ToolRegistry.retrieve_by_description. |
TestExecuteWithRequestCapability |
Tests for the execute() API with request_capability support. |
Tests for get_request_capability_tool and is_request_capability_tool.
test_is_request_capability_tool_false_for_empty_dict()
Tests for extract_request_capability_call.
| METHOD | DESCRIPTION |
|---|---|
test_extracts_from_raw_messages |
|
test_returns_none_when_no_request_capability |
|
test_returns_none_for_empty_messages |
|
test_returns_none_for_messages_without_tool_calls |
|
test_extracts_from_last_message_with_rc |
Should find rc even if it's not the very last message. |
test_handles_dict_arguments |
Arguments might already be parsed as dict by some providers. |
test_handles_missing_description_gracefully |
|
test_returns_none_for_messages_without_tool_calls()
test_extracts_from_last_message_with_rc()
Should find rc even if it's not the very last message.
test_handles_dict_arguments()
Arguments might already be parsed as dict by some providers.
Tests for the _tokenize helper.
| METHOD | DESCRIPTION |
|---|---|
test_simple_words |
|
test_handles_punctuation |
|
test_handles_camel_case |
|
test_handles_underscores |
|
test_no_duplicates |
|
test_empty_string |
|
test_removes_short_tokens |
|
Tests for score_capability.
| METHOD | DESCRIPTION |
|---|---|
test_exact_match_scores_1 |
|
test_partial_match_scores_partial |
|
test_no_match_scores_0 |
|
test_empty_query_scores_0 |
|
test_substring_match |
|
Tests for ToolRegistry.retrieve_by_description.
| METHOD | DESCRIPTION |
|---|---|
test_returns_matching_capabilities |
|
test_returns_empty_for_no_match |
|
test_respects_k_limit |
|
test_sorts_by_relevance |
|
test_empty_description_returns_empty |
|
test_searches_all_scopes |
|
Tests for the execute() API with request_capability support.
| METHOD | DESCRIPTION |
|---|---|
test_max_retrieval_rounds_zero_no_rc_tool |
With max_retrieval_rounds=0, request_capability should NOT be in |
test_max_retrieval_rounds_one_injects_rc_tool |
With max_retrieval_rounds=1, request_capability IS in the |
test_request_capability_interception_single_round |
Agent calls request_capability, gets new tools, re-dispatches, |
test_two_retrieval_rounds |
Agent uses request_capability twice with max_retrieval_rounds=2. |
test_rounds_exhausted_rc_removed |
After max_retrieval_rounds uses, request_capability is |
test_synthetic_now_available_in_history |
The synthetic 'Now available: ...' message should appear in |
test_no_request_capability_call_proceeds_normally |
If agent never calls request_capability, execution proceeds |
test_request_capability_no_registry_graceful |
If tool_registry is None, rc tool is not injected and |
test_rc_not_injected_when_rounds_zero_stream |
In streaming mode, rc tool should not be injected with 0 rounds. |
test_rc_interception_during_stream |
During streaming, when agent calls request_capability, it is |
test_stream_rc_rounds_exhausted |
In streaming with max_retrieval_rounds=1, after 1 rc call, |
async
¤
test_max_retrieval_rounds_zero_no_rc_tool()
With max_retrieval_rounds=0, request_capability should NOT be in the toolset.
async
¤
test_max_retrieval_rounds_one_injects_rc_tool()
With max_retrieval_rounds=1, request_capability IS in the toolset.
async
¤
test_request_capability_interception_single_round()
Agent calls request_capability, gets new tools, re-dispatches, and produces output.
async
¤
test_two_retrieval_rounds()
Agent uses request_capability twice with max_retrieval_rounds=2.
async
¤
test_rounds_exhausted_rc_removed()
After max_retrieval_rounds uses, request_capability is removed from toolset.
async
¤
test_synthetic_now_available_in_history()
The synthetic 'Now available: ...' message should appear in conversation history.
async
¤
test_no_request_capability_call_proceeds_normally()
If agent never calls request_capability, execution proceeds as if it weren't there.
async
¤
test_request_capability_no_registry_graceful()
If tool_registry is None, rc tool is not injected and execution proceeds normally.
async
¤
test_rc_not_injected_when_rounds_zero_stream()
In streaming mode, rc tool should not be injected with 0 rounds.
async
¤
test_rc_interception_during_stream()
During streaming, when agent calls request_capability, it is intercepted and tools are expanded.
async
¤
test_stream_rc_rounds_exhausted()
In streaming with max_retrieval_rounds=1, after 1 rc call, rc tool is removed and 3rd attempt works without it.