Skip to content

Commit d274d7b

Browse files
h3xxitactions-userperrozzicubic-dev-ai[bot]
authored
📚 Enhance v1.0 Documentation: Add Protocol Guides, Implementation Examples, and User Navigation (#43)
* chore: update contributors data 2025-09-04 * chore: update contributors data 2025-09-04 * chore: update contributors data 2025-09-05 * Add comprehensive v1.0 documentation - Add complete communication protocols documentation (HTTP, WebSocket, SSE, CLI, Text, MCP) - Add implementation guide with Python examples and multi-language references - Add for-tool-providers guide with practical examples - Add migration guide from v0.1 to v1.0 - Update sidebar navigation structure - Address incomplete current version documentation gap * Improve landing page, security, and UTCP vs MCP documentation - Rewrite docs/index.md with better structure, clear value proposition, and navigation - Enhance docs/security.md with comprehensive protocol-specific security guidance - Improve docs/utcp-vs-mcp.md with technical depth, migration guidance, and decision framework - Add language specification notes consistently across documentation - Include practical examples and cross-references throughout * Update docs/index.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Add missing API documentation for core classes - Add class descriptions for UtcpClient, serializers, and auth implementations - Add documentation for tool repository and variable loader classes - Add call template documentation for HTTP, CLI, Text, and SSE protocols - Fix 'No class documentation available' entries with minimal descriptions * Fix providers/index.md ID for sidebar compatibility * Revert "Add missing API documentation for core classes" This reverts commit 2eb1439. * Update terminology from providers to protocol plugins - Rename docs/providers to docs/protocols for v1.0 terminology - Update sidebars.ts to reference protocols/ paths - Update protocols/index.md with correct plugin-based architecture description - Replace 'providers' with 'protocol plugins' throughout documentation - Align with v1.0 call template terminology * Phase 1: Make protocol documentation language-independent - Remove Python-specific examples from specification protocols - Replace with JSON/YAML configuration examples - Add references to language-specific documentation - Keep protocol concepts and architecture language-agnostic * Continue Phase 1: Remove Python dependencies from core docs - Replace implementation.md with language-independent version - Remove Python examples from index.md quick start - Replace with JSON configuration and conceptual descriptions - Add references to language-specific documentation * Complete Phase 1: Remove final Python dependencies - Replace remaining Python example in for-tool-providers.md - All core documentation now language-independent - Python-specific examples moved to python-utcp repository - JSON/YAML configuration examples throughout * Remove Python language bias from documentation - Remove Python-specific language from intro sections - Make language references neutral in index.md and for-tool-providers.md - Keep Python examples in CLI/MCP protocols as they're just examples - Update links to be language-neutral * Start removing Python code from security.md while preserving JSON - Remove Python language bias from intro - Replace Python implementation examples with language-independent guidance - Keep all JSON configuration examples - Preserve security concepts and best practices * Continue removing Python code from security.md - Replace path validation Python example with requirements - Preserve JSON configuration examples - Keep security concepts language-independent * Remove Python language bias from specification - Convert Python code examples to language-agnostic descriptions - Replace Python-specific documentation links with multi-language references - Maintain technical accuracy while ensuring language neutrality - Major files updated: utcp-vs-mcp.md, migration-v0.1-to-v1.0.md - Updated documentation links across all protocol files * Remove UTCP specification field requirements from documentation - Remove field requirement tables (Required/Optional Fields) from protocol docs - Remove UTCP manual structure requirement tables from tool provider guide - Replace with references to API specification documentation - Keep API input/output schema examples as they describe tool interfaces - Eliminates duplication between user docs and API specification * Remove Express.js implementation section - Remove technology-specific implementation example - Keep language-agnostic conceptual guidance - Maintain focus on UTCP concepts rather than specific frameworks * Updated API spec * Update docs * Update 1.0 versioned docs --------- Co-authored-by: GitHub Action <action@github.com> Co-authored-by: Luca Perrozzi <ilperrozzi@gmail.com> Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
1 parent a820b17 commit d274d7b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+10950
-708
lines changed

‎docs/api/core/utcp/exceptions/utcp_serializer_validation_error.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,20 @@ sidebar_label: utcp_serializer_validation_error
99

1010
### class UtcpSerializerValidationError {#utcpserializervalidationerror}
1111

12-
*No class documentation available*
12+
<details>
13+
<summary>Documentation</summary>
14+
15+
Exception raised when a serializer validation fails.
16+
17+
Thrown by serializers when they cannot validate or convert data structures
18+
due to invalid format, missing required fields, or type mismatches.
19+
Contains the original validation error details for debugging.
20+
21+
22+
**Usage**
23+
24+
Typically caught when loading configuration files or processing
25+
external data that doesn't conform to UTCP specifications.
26+
</details>
1327

1428
---

‎docs/api/core/utcp/implementations/post_processors/filter_dict_post_processor.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: filter_dict_post_processor
3+
sidebar_label: filter_dict_post_processor
4+
---
5+
6+
# filter_dict_post_processor
7+
8+
**File:** `core/src/utcp/implementations/post_processors/filter_dict_post_processor.py`
9+
10+
### class FilterDictPostProcessor ([ToolPostProcessor](./../../interfaces/tool_post_processor.md#toolpostprocessor)) {#filterdictpostprocessor}
11+
12+
<details>
13+
<summary>Documentation</summary>
14+
15+
Post-processor that filters dictionary keys from tool results.
16+
17+
Provides flexible filtering capabilities to include or exclude specific keys
18+
from dictionary results, with support for nested dictionaries and lists.
19+
Can be configured to apply filtering only to specific tools or manuals.
20+
21+
22+
**Attributes**
23+
24+
- **`tool_post_processor_type`**: Always "filter_dict" for this processor.
25+
- **`exclude_keys`**: List of keys to remove from dictionary results.
26+
- **`only_include_keys`**: List of keys to keep in dictionary results (all others removed).
27+
- **`exclude_tools`**: List of tool names to skip processing for.
28+
- **`only_include_tools`**: List of tool names to process (all others skipped).
29+
- **`exclude_manuals`**: List of manual names to skip processing for.
30+
- **`only_include_manuals`**: List of manual names to process (all others skipped).
31+
</details>
32+
33+
#### Fields:
34+
35+
- tool_post_processor_type: Literal['filter_dict']
36+
- exclude_keys: Optional[List[str]]
37+
- only_include_keys: Optional[List[str]]
38+
- exclude_tools: Optional[List[str]]
39+
- only_include_tools: Optional[List[str]]
40+
- exclude_manuals: Optional[List[str]]
41+
- only_include_manuals: Optional[List[str]]
42+
43+
---
44+
45+
### class FilterDictPostProcessorConfigSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[FilterDictPostProcessor]) {#filterdictpostprocessorconfigserializer}
46+
47+
*No class documentation available*
48+
49+
---

‎docs/api/core/utcp/implementations/post_processors/limit_strings_post_processor.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: limit_strings_post_processor
3+
sidebar_label: limit_strings_post_processor
4+
---
5+
6+
# limit_strings_post_processor
7+
8+
**File:** `core/src/utcp/implementations/post_processors/limit_strings_post_processor.py`
9+
10+
### class LimitStringsPostProcessor ([ToolPostProcessor](./../../interfaces/tool_post_processor.md#toolpostprocessor)) {#limitstringspostprocessor}
11+
12+
<details>
13+
<summary>Documentation</summary>
14+
15+
Post-processor that limits the length of string values in tool results.
16+
17+
Truncates string values to a specified maximum length to prevent
18+
excessively large responses. Processes nested dictionaries and lists
19+
recursively. Can be configured to apply limiting only to specific
20+
tools or manuals.
21+
22+
23+
**Attributes**
24+
25+
- **`tool_post_processor_type`**: Always "limit_strings" for this processor.
26+
- **`limit`**: Maximum length for string values (default: 10000 characters).
27+
- **`exclude_tools`**: List of tool names to skip processing for.
28+
- **`only_include_tools`**: List of tool names to process (all others skipped).
29+
- **`exclude_manuals`**: List of manual names to skip processing for.
30+
- **`only_include_manuals`**: List of manual names to process (all others skipped).
31+
</details>
32+
33+
#### Fields:
34+
35+
- tool_post_processor_type: Literal['limit_strings']
36+
- limit: int
37+
- exclude_tools: Optional[List[str]]
38+
- only_include_tools: Optional[List[str]]
39+
- exclude_manuals: Optional[List[str]]
40+
- only_include_manuals: Optional[List[str]]
41+
42+
---
43+
44+
### class LimitStringsPostProcessorConfigSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[LimitStringsPostProcessor]) {#limitstringspostprocessorconfigserializer}
45+
46+
*No class documentation available*
47+
48+
---

‎docs/api/core/utcp/implementations/tag_search.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,38 @@ sidebar_label: tag_search
99

1010
### class TagAndDescriptionWordMatchStrategy ([ToolSearchStrategy](./../interfaces/tool_search_strategy.md#toolsearchstrategy)) {#taganddescriptionwordmatchstrategy}
1111

12-
*No class documentation available*
12+
<details>
13+
<summary>Documentation</summary>
14+
15+
Tag and description word match strategy.
16+
17+
18+
**Implements A Weighted Scoring System That Matches Tools Based On**
19+
20+
1. Tag matches (higher weight)
21+
2. Description word matches (lower weight)
22+
23+
The strategy normalizes queries to lowercase, extracts words using regex,
24+
and calculates relevance scores for each tool. Results are sorted by
25+
score in descending order.
26+
27+
28+
29+
**Attributes**
30+
31+
- **`tool_search_strategy_type`**: Always "tag_and_description_word_match".
32+
- **`description_weight`**: Weight multiplier for description word matches (default: 1.0).
33+
- **`tag_weight`**: Weight multiplier for tag matches (default: 3.0).
34+
35+
36+
37+
**Scoring Algorithm**
38+
39+
- Each matching tag contributes tag_weight points
40+
- Each matching description word contributes description_weight points
41+
- Tools with higher scores are ranked first
42+
- Tools with zero score are included in results (ranked last)
43+
</details>
1344

1445
#### Fields:
1546

‎docs/api/core/utcp/plugins/plugin_loader.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@ sidebar_label: plugin_loader
77

88
**File:** `core/src/utcp/plugins/plugin_loader.py`
99

10+
### Function _load_plugins() {#_load_plugins}
11+
12+
*No function documentation available*
13+
14+
---
15+
1016
### Function ensure_plugins_initialized() {#ensure_plugins_initialized}
1117

1218
*No function documentation available*

‎docs/api/index.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ This specification is organized by module of the reference python implementation
1111

1212
**Note:** The modules don't have to be implemented in the same way as in the reference implementation, but all of the functionality here needs to be provided.
1313

14-
**Total documented items:** 189
15-
**Modules documented:** 39
14+
**Total documented items:** 195
15+
**Modules documented:** 41
1616

1717
## Core Modules
1818

@@ -93,6 +93,16 @@ Core UTCP framework components that define the fundamental interfaces and implem
9393
- **Contains:** 2 classes, 12 methods
9494

9595

96+
### [utcp.implementations.post_processors.filter_dict_post_processor](./core\utcp\implementations\post_processors\filter_dict_post_processor.md)
97+
98+
- **Contains:** 2 classes
99+
100+
101+
### [utcp.implementations.post_processors.limit_strings_post_processor](./core\utcp\implementations\post_processors\limit_strings_post_processor.md)
102+
103+
- **Contains:** 2 classes
104+
105+
96106
### [utcp.implementations.tag_search](./core\utcp\implementations\tag_search.md)
97107

98108
- **Contains:** 2 classes, 3 methods
@@ -140,7 +150,7 @@ Core UTCP framework components that define the fundamental interfaces and implem
140150

141151
### [utcp.plugins.plugin_loader](./core\utcp\plugins\plugin_loader.md)
142152

143-
- **Contains:** 1 functions
153+
- **Contains:** 2 functions
144154

145155

146156
### [utcp.utcp_client](./core\utcp\utcp_client.md)
@@ -154,7 +164,7 @@ Plugin implementations that extend UTCP with specific transport protocols and ca
154164

155165
### [communication_protocols.cli.src.utcp_cli.cli_call_template](./plugins\communication_protocols\cli\src\utcp_cli\cli_call_template.md)
156166

157-
- **Contains:** 2 classes, 2 methods
167+
- **Contains:** 3 classes, 2 methods
158168

159169

160170
### [communication_protocols.cli.src.utcp_cli.cli_communication_protocol](./plugins\communication_protocols\cli\src\utcp_cli\cli_communication_protocol.md)

0 commit comments

Comments
 (0)