Update version 1.0 #49
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
| ```json | ||
| { | ||
| "max_size": 1048576 // 1MB limit | ||
| "manual_call_template": { /* original template */ }, |
Contributor
There was a problem hiding this comment.
JSON example uses /* */ inside an object; JSON doesn’t support comments. Remove the comment to keep the example valid.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/text.md at line 188:
<comment>JSON example uses /* */ inside an object; JSON doesn’t support comments. Remove the comment to keep the example valid.</comment>
<file context>
@@ -6,432 +6,216 @@ sidebar_position: 5
```json
{
- "max_size": 1048576 // 1MB limit
+ "manual_call_template": { /* original template */ },
+ "manual": { "tools": [] },
+ "success": false,
</file context>
Suggested change
| "manual_call_template": { /* original template */ }, | |
| "manual_call_template": {}, |
| ### JSON Files | ||
|
|
||
| ```json | ||
| // /path/to/manual.json |
Contributor
There was a problem hiding this comment.
JSON code block contains a // comment line, which is invalid JSON. Remove the comment or move it outside the JSON block.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/text.md at line 147:
<comment>JSON code block contains a // comment line, which is invalid JSON. Remove the comment or move it outside the JSON block.</comment>
<file context>
@@ -6,432 +6,216 @@ sidebar_position: 5
+### JSON Files
```json
+// /path/to/manual.json
{
- "transform": "normalize_whitespace" // Normalize all whitespace
</file context>
| "max_size": 65536 | ||
| } | ||
| "call_template_type": "text", | ||
| "file_path": "manuals/my_tools.json" // Resolved against client root_dir |
Contributor
There was a problem hiding this comment.
JSON example includes a trailing // comment, which is invalid JSON and may confuse readers. Remove the comment or move it to surrounding prose.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/text.md at line 66:
<comment>JSON example includes a trailing // comment, which is invalid JSON and may confuse readers. Remove the comment or move it to surrounding prose.</comment>
<file context>
@@ -6,432 +6,216 @@ sidebar_position: 5
- "max_size": 65536
- }
+ "call_template_type": "text",
+ "file_path": "manuals/my_tools.json" // Resolved against client root_dir
}
</file context>
</details>
```suggestion
"file_path": "manuals/my_tools.json"
| The Text call template has a simple structure for reading UTCP manuals from files. For complete field specifications and validation rules, see the [Text Call Template API Reference](../api/plugins/communication_protocols/text/src/utcp_text/text_call_template.md). | ||
|
|
||
| ## File Sources | ||
| ### Required Fields |
Contributor
There was a problem hiding this comment.
Heading labels these as required, but auth is not required (it's always None). Rename the heading to avoid implying auth must be supplied.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/text.md at line 31:
<comment>Heading labels these as required, but auth is not required (it's always None). Rename the heading to avoid implying auth must be supplied.</comment>
<file context>
@@ -6,432 +6,216 @@ sidebar_position: 5
+The Text call template has a simple structure for reading UTCP manuals from files. For complete field specifications and validation rules, see the [Text Call Template API Reference](../api/plugins/communication_protocols/text/src/utcp_text/text_call_template.md).
-## File Sources
+### Required Fields
-### Local Files
</file context>
Suggested change
| ### Required Fields | |
| ### Fields |
| client = UtcpClient() | ||
|
|
||
| # Register streamable HTTP provider | ||
| await client.register_tool_provider(streamable_http_manual) |
Contributor
There was a problem hiding this comment.
The usage example calls UtcpClient.register_tool_provider, which does not exist; use register_manual instead to align with the documented API.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/streamable-http.md at line 249:
<comment>The usage example calls UtcpClient.register_tool_provider, which does not exist; use register_manual instead to align with the documented API.</comment>
<file context>
@@ -99,7 +163,105 @@ Errors are handled similarly to the standard HTTP protocol:
+ client = UtcpClient()
+
+ # Register streamable HTTP provider
+ await client.register_tool_provider(streamable_http_manual)
+
+ # Stream large dataset
</file context>
Suggested change
| await client.register_tool_provider(streamable_http_manual) | |
| await client.register_manual(streamable_http_manual) |
| client = UtcpClient() | ||
|
|
||
| # Register SSE provider | ||
| await client.register_tool_provider(sse_manual) |
Contributor
There was a problem hiding this comment.
Define the provider variable used in the example or reference an existing example provider to avoid undefined-name errors.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/sse.md at line 412:
<comment>Define the provider variable used in the example or reference an existing example provider to avoid undefined-name errors.</comment>
<file context>
@@ -318,47 +341,86 @@ data: {"message": "Simple data without event type"}
+ client = UtcpClient()
+
+ # Register SSE provider
+ await client.register_tool_provider(sse_manual)
+
+ # Stream events with automatic filtering and reconnection
</file context>
| "retry_timeout": 30000, | ||
| "auth": { | ||
| "auth_type": "api_key", | ||
| "api_key": "${STOCK_API_KEY}", |
Contributor
There was a problem hiding this comment.
Use a Bearer-prefixed value for Authorization to align with the API Key Authentication example and common practice.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/sse.md at line 177:
<comment>Use a Bearer-prefixed value for Authorization to align with the API Key Authentication example and common practice.</comment>
<file context>
@@ -133,27 +162,21 @@ SSE uses standard HTTP authentication methods:
+ "retry_timeout": 30000,
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${STOCK_API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
</file context>
Suggested change
| "api_key": "${STOCK_API_KEY}", | |
| "api_key": "Bearer ${STOCK_API_KEY}", |
| "manual_call_templates": [{ | ||
| "name": "github_manual", | ||
| "call_template_type": "text", | ||
| "file_path": "./github_manual.json", |
Contributor
There was a problem hiding this comment.
Remove the trailing comma after file_path to make the JSON valid.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/index.md at line 122:
<comment>Remove the trailing comma after file_path to make the JSON valid.</comment>
<file context>
@@ -72,31 +81,55 @@ Add a discovery endpoint to your existing API:
+ "manual_call_templates": [{
+ "name": "github_manual",
+ "call_template_type": "text",
+ "file_path": "./github_manual.json",
+ }]
+}
</file context>
Suggested change
| "file_path": "./github_manual.json", | |
| "file_path": "./github_manual.json" |
| Add a discovery endpoint to your existing API: | ||
| **Option A: Discovery via existing OpenAPI spec** | ||
|
|
||
| **Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json` |
Contributor
There was a problem hiding this comment.
Use HTTPS for the GitHub OpenAPI endpoint to avoid mixed content and ensure correctness.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/index.md at line 53:
<comment>Use HTTPS for the GitHub OpenAPI endpoint to avoid mixed content and ensure correctness.</comment>
<file context>
@@ -44,7 +48,12 @@ npm install @utcp/core @utcp/http
-Add a discovery endpoint to your existing API:
+**Option A: Discovery via existing OpenAPI spec**
+
+**Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json`
+
+
</file context>
Suggested change
| **Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json` | |
| **Generate OpenAPI endpoint**: `GET https://api.github.com/openapi.json` |
| "name": "weather_api", | ||
| "call_template_type": "http", | ||
| "url": "http://localhost:8000/utcp", | ||
| "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically |
Contributor
There was a problem hiding this comment.
Inline comment makes the JSON invalid and not copy-pasteable; move the note to surrounding text or remove the comment.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/index.md at line 95:
<comment>Inline comment makes the JSON invalid and not copy-pasteable; move the note to surrounding text or remove the comment.</comment>
<file context>
@@ -72,31 +81,55 @@ Add a discovery endpoint to your existing API:
"name": "weather_api",
"call_template_type": "http",
- "url": "http://localhost:8000/utcp",
+ "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically
"http_method": "GET"
}]
</file context>
Suggested change
| "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically | |
| "url": "http://localhost:8000/utcp", |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary by cubic
Overhauled v1.0 docs to align with current protocol behavior, add OpenAPI compatibility, and remove WebSocket references. Clarifies parameter mapping, auth, security, and updates examples across HTTP, MCP, SSE, Streamable HTTP, Text, and Quick Start.
New Features
Migration