venn-cli 0.1.0__tar.gz

venn_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest -m "not integration" -v

venn_cli-0.1.0/.github/workflows/publish-pypi.yaml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

venn_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+.env

venn_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moda Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

venn_cli-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: venn-cli
+Version: 0.1.0
+Summary: CLI for the Venn ToolIQ API
+Project-URL: Homepage, https://github.com/moda-labs/venn-cli
+Project-URL: Repository, https://github.com/moda-labs/venn-cli
+Project-URL: Issues, https://github.com/moda-labs/venn-cli/issues
+Author-email: Moda Labs <zach@modalabs.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'

venn_cli-0.1.0/VERSION

@@ -0,0 +1 @@
+0.1.0

venn_cli-0.1.0/docs/openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"ToolIQ REST API","description":"REST API for tool discovery, search, and execution","version":"1.0.0"},"paths":{"/tools/list":{"get":{"summary":"Api List All Tools","description":"List all tools for a server with metadata. Requires one of: slug, directory_id, or instance_id. Returns server name, version, and tool metadata.","operationId":"api_list_all_tools_tools_list_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"directory_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Server directory UUID","title":"Directory Id"},"description":"Server directory UUID"},{"name":"instance_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Server instance UUID","title":"Instance Id"},"description":"Server instance UUID"},{"name":"slug","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Toolset slug (e.g., 'salesforce', 'gmail')","title":"Slug"},"description":"Toolset slug (e.g., 'salesforce', 'gmail')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListToolsSuccessResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/tools/search":{"post":{"summary":"Api Search Tools","description":"Search for tools across connected MCP servers using semantic similarity. Returns ranked results with scores, supports pagination and filtering.","operationId":"api_search_tools_tools_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchToolsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchToolsSuccessResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/tools/describe":{"post":{"summary":"Api Describe Tools","description":"Get detailed schema information for one or more tools including inputSchema, description, and write operation metadata.","operationId":"api_describe_tools_tools_describe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DescribeToolsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DescribeToolsSuccessResponse"}}}},"400":{"description":"Invalid request or tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/tools/execute":{"post":{"summary":"Api Execute Tool","description":"Execute a specific tool on a connected MCP server. Supports audit operations with confirmation tokens.","operationId":"api_execute_tool_tools_execute_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteToolRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteToolSuccessResponse"}}}},"400":{"description":"Invalid request or execution failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Server not connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/tools/execute-workflow":{"post":{"summary":"Api Execute Code","description":"Execute Python code in a sandboxed environment for programmatic tool calling with access to async_call_tool() and async_call_skill() (call sites must `await`).","operationId":"api_execute_code_tools_execute_workflow_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteCodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteCodeSuccessResponse"}}}},"400":{"description":"Invalid request or code execution failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"408":{"description":"Code execution timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/tools/help":{"post":{"summary":"Api Help","description":"Get help information, server status, and authentication URLs. Supports actions: getting_started, connector_help, auth_helper, list_servers.","operationId":"api_help_tools_help_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HelpRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HelpSuccessResponse"}}}},"400":{"description":"Invalid action or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/tools/confirm":{"post":{"summary":"Api Confirm Write Operation","description":"Get a confirmation token for executing write operations.\n\nRequest body: {} (no parameters required)\n\nAuthentication:\n    Requires Bearer token in Authorization header","operationId":"api_confirm_write_operation_tools_confirm_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmWriteOperationSuccessResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/skills":{"post":{"summary":"Api Upsert Skill","description":"Create or update an executable skill. Writes the YAML to disk and reloads the index.\n\nThis endpoint is intended for local development use (e.g., from the create-skill CLI command).\nDeployed environments must opt in explicitly with TOOL_ROUTER_SKILL_UPSERT_ENABLED.","operationId":"api_upsert_skill_skills_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertSkillRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Endpoint disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid skill YAML","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/toolset/{toolset_key}/history":{"get":{"summary":"Api List Catalog History","description":"Catalog (YAML) history for a 1st-party toolset, newest first.","operationId":"api_list_catalog_history_toolset__toolset_key__history_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"toolset_key","in":"path","required":true,"schema":{"type":"string","title":"Toolset Key"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"before_version","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Before Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogHistorySuccessResponse"}}}},"404":{"description":"Toolset has no catalog history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"History unavailable — DB temporarily unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/server/{directory_id}/history":{"get":{"summary":"Api List Server History","description":"Per-server-instance history, newest first. Works for any connected\nserver including 3rd-party — caller must supply `directory_id`.","operationId":"api_list_server_history_server__directory_id__history_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"directory_id","in":"path","required":true,"schema":{"type":"string","title":"Directory Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"before_version","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Before Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerHistorySuccessResponse"}}}},"404":{"description":"No history for this directory_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"History unavailable — DB temporarily unreachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CatalogHistoryData":{"properties":{"toolset_key":{"type":"string","title":"Toolset Key"},"revisions":{"items":{"$ref":"#/components/schemas/RevisionSummary"},"type":"array","title":"Revisions"}},"type":"object","required":["toolset_key","revisions"],"title":"CatalogHistoryData","description":"Data returned by /toolset/{toolset_key}/history endpoint."},"CatalogHistorySuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/CatalogHistoryData"}},"type":"object","required":["result"],"title":"CatalogHistorySuccessResponse","description":"Success response for /toolset/{toolset_key}/history."},"ConfirmWriteOperationData":{"properties":{"confirmation_token":{"type":"string","title":"Confirmation Token"},"expires_in_seconds":{"type":"integer","title":"Expires In Seconds"},"usage":{"type":"string","title":"Usage"},"important":{"type":"string","title":"Important"}},"type":"object","required":["confirmation_token","expires_in_seconds","usage","important"],"title":"ConfirmWriteOperationData","description":"Data returned by confirm_write_operation endpoint."},"ConfirmWriteOperationSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/ConfirmWriteOperationData"}},"type":"object","required":["result"],"title":"ConfirmWriteOperationSuccessResponse","description":"Success response for /tools/confirm endpoint."},"DescribeToolsData":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ToolDetailsData"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"DescribeToolsData","description":"Data returned by describe_tools endpoint."},"DescribeToolsRequest":{"properties":{"tools":{"items":{"$ref":"#/components/schemas/ToolIdentifier"},"type":"array","title":"Tools","description":"List of tool identifiers"},"refresh":{"type":"boolean","title":"Refresh","description":"Bypass cache","default":false}},"type":"object","required":["tools"],"title":"DescribeToolsRequest"},"DescribeToolsSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/DescribeToolsData"}},"type":"object","required":["result"],"title":"DescribeToolsSuccessResponse","description":"Success response for /tools/describe endpoint."},"ErrorResponse":{"properties":{"success":{"type":"boolean","const":false,"title":"Success","default":false},"version":{"type":"string","title":"Version"},"error":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}],"title":"Error","description":"Error message or structured error details"}},"type":"object","required":["error"],"title":"ErrorResponse","description":"Response model for error responses."},"ExecuteCodeData":{"properties":{"result":{"title":"Result"}},"type":"object","required":["result"],"title":"ExecuteCodeData","description":"Data returned by execute_code endpoint."},"ExecuteCodeRequest":{"properties":{"code":{"type":"string","title":"Code","description":"Python code to execute"},"timeout":{"type":"integer","maximum":360.0,"minimum":1.0,"title":"Timeout","description":"Maximum execution time in seconds","default":180},"confirmed":{"type":"boolean","title":"Confirmed","description":"For write operations, set to True after user approval","default":false},"confirmation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirmation Token","description":"Required when confirmed=True"}},"type":"object","required":["code"],"title":"ExecuteCodeRequest"},"ExecuteCodeSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/ExecuteCodeData"}},"type":"object","required":["result"],"title":"ExecuteCodeSuccessResponse","description":"Success response for /tools/execute-code endpoint."},"ExecuteToolRequest":{"properties":{"server_id":{"type":"string","title":"Server Id","description":"Server identifier"},"tool_name":{"type":"string","title":"Tool Name","description":"Tool name"},"tool_args":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Args","description":"Tool arguments"},"refresh":{"type":"boolean","title":"Refresh","description":"Bypass cache","default":false},"confirmed":{"type":"boolean","title":"Confirmed","description":"For write operations, set to True after user approval","default":false},"confirmation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirmation Token","description":"Required when confirmed=True"}},"type":"object","required":["server_id","tool_name"],"title":"ExecuteToolRequest"},"ExecuteToolSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"title":"Result"}},"type":"object","required":["result"],"title":"ExecuteToolSuccessResponse","description":"Success response for /tools/execute endpoint."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HelpRequest":{"properties":{"action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action","description":"Help action: getting_started, connector_help, auth_helper, list_servers"},"server_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Server Id","description":"Server identifier (required for auth_helper)"},"refresh":{"type":"boolean","title":"Refresh","description":"Bypass cache","default":false}},"type":"object","title":"HelpRequest"},"HelpSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{"additionalProperties":true,"type":"object"},"type":"array"}],"title":"Result"}},"type":"object","required":["result"],"title":"HelpSuccessResponse","description":"Success response for /tools/help endpoint."},"ListToolsData":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"toolset_version":{"type":"string","title":"Toolset Version"},"tools":{"items":{"$ref":"#/components/schemas/ToolMetadata"},"type":"array","title":"Tools"},"instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instance Id"},"directory_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Directory Id"}},"type":"object","required":["name","slug","toolset_version","tools","instance_id","directory_id"],"title":"ListToolsData","description":"Data returned by list_tools endpoint."},"ListToolsSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/ListToolsData"}},"type":"object","required":["result"],"title":"ListToolsSuccessResponse","description":"Success response for /tools/list endpoint."},"RevisionSummary":{"properties":{"version":{"type":"integer","title":"Version"},"transaction_id":{"type":"string","title":"Transaction Id"},"issued_at":{"type":"string","format":"date-time","title":"Issued At"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"summary":{"additionalProperties":{"type":"integer"},"type":"object","title":"Summary"}},"type":"object","required":["version","transaction_id","issued_at","summary"],"title":"RevisionSummary","description":"A single revision in a toolset's or server's history.\n\n`version` is a 0-indexed counter scoped to the slice (toolset_key OR\ndirectory_id; v0 = oldest revision in that slice). `transaction_id` is\nthe underlying global Continuum transaction id, exposed for debugging."},"SearchToolsData":{"properties":{"candidates":{"items":{"anyOf":[{"$ref":"#/components/schemas/ToolCandidate"},{"$ref":"#/components/schemas/SkillCandidate"}]},"type":"array","title":"Candidates"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["candidates","total","limit","offset"],"title":"SearchToolsData","description":"Data returned by search_tools endpoint.\n\nReturns a unified list of tools and skills ranked by relevance.\nEach candidate has a 'type' field to distinguish between tools and skills."},"SearchToolsRequest":{"properties":{"query":{"type":"string","title":"Query","description":"Search query text"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"Maximum number of results","default":10},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of results to skip","default":0},"min_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Score","description":"Minimum similarity score threshold","default":0.3},"min_results":{"type":"integer","minimum":0.0,"title":"Min Results","description":"Minimum results to return even if below threshold","default":5},"refresh":{"type":"boolean","title":"Refresh","description":"Bypass cache to get updated servers","default":false}},"type":"object","required":["query"],"title":"SearchToolsRequest"},"SearchToolsSuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/SearchToolsData"}},"type":"object","required":["result"],"title":"SearchToolsSuccessResponse","description":"Success response for /tools/search endpoint."},"ServerHistoryData":{"properties":{"directory_id":{"type":"string","title":"Directory Id"},"revisions":{"items":{"$ref":"#/components/schemas/RevisionSummary"},"type":"array","title":"Revisions"}},"type":"object","required":["directory_id","revisions"],"title":"ServerHistoryData","description":"Data returned by /server/{directory_id}/history endpoint."},"ServerHistorySuccessResponse":{"properties":{"success":{"type":"boolean","const":true,"title":"Success","default":true},"version":{"type":"string","title":"Version"},"result":{"$ref":"#/components/schemas/ServerHistoryData"}},"type":"object","required":["result"],"title":"ServerHistorySuccessResponse","description":"Success response for /server/{directory_id}/history."},"SkillCandidate":{"properties":{"type":{"type":"string","const":"skill","title":"Type","default":"skill"},"rank":{"type":"integer","title":"Rank"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["rank","name","description"],"title":"SkillCandidate","description":"Lightweight skill summary in search results.\n\nReturns minimal information to save context tokens.\nUse describe_skill tool to retrieve full pattern content."},"ToolCandidate":{"properties":{"type":{"type":"string","const":"tool","title":"Type","default":"tool"},"rank":{"type":"integer","title":"Rank"},"server_id":{"type":"string","title":"Server Id"},"server_name":{"type":"string","title":"Server Name"},"tool_name":{"type":"string","title":"Tool Name"},"short_description":{"type":"string","title":"Short Description"},"server_connected":{"type":"boolean","title":"Server Connected"},"annotations":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Annotations"}},"type":"object","required":["rank","server_id","server_name","tool_name","short_description","server_connected"],"title":"ToolCandidate","description":"Individual tool in search results."},"ToolDetailsData":{"properties":{"server_id":{"type":"string","title":"Server Id"},"server_name":{"type":"string","title":"Server Name"},"tool_name":{"type":"string","title":"Tool Name"},"description":{"type":"string","title":"Description"},"extended_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extended Description"},"inputSchema":{"additionalProperties":true,"type":"object","title":"Inputschema"},"outputSchema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Outputschema"},"write_operation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Write Operation"},"preview_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview Template"},"annotations":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Annotations"}},"type":"object","required":["server_id","server_name","tool_name","description","inputSchema"],"title":"ToolDetailsData","description":"Detailed schema information for a single tool."},"ToolIdentifier":{"properties":{"server_id":{"type":"string","title":"Server Id","description":"Server identifier"},"tool_name":{"type":"string","title":"Tool Name","description":"Tool name"}},"type":"object","required":["server_id","tool_name"],"title":"ToolIdentifier"},"ToolMetadata":{"properties":{"tool_name":{"type":"string","title":"Tool Name"},"readable_name":{"type":"string","title":"Readable Name"},"short_description":{"type":"string","title":"Short Description"},"crud_operation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Crud Operation"},"status":{"type":"string","title":"Status"},"risk_level":{"type":"integer","title":"Risk Level"},"audit":{"type":"boolean","title":"Audit"},"paywalled":{"type":"boolean","title":"Paywalled"}},"type":"object","required":["tool_name","readable_name","short_description","crud_operation","status","risk_level","audit","paywalled"],"title":"ToolMetadata","description":"Metadata for a single tool in a toolset."},"UpsertSkillRequest":{"properties":{"content":{"type":"string","title":"Content","description":"Full YAML content of the skill file"}},"type":"object","required":["content"],"title":"UpsertSkillRequest","description":"Request body for POST /skills — create or update an executable skill."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"JWT Bearer token from Barndoor platform","scheme":"bearer"}}},"servers":[{"url":"/tooliq/api","description":"ToolIQ REST API"}]}

venn_cli-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "venn-cli"
+version = "0.1.0"
+description = "CLI for the Venn ToolIQ API"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Moda Labs", email = "zach@modalabs.ai" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "rich>=13.0",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/moda-labs/venn-cli"
+Repository = "https://github.com/moda-labs/venn-cli"
+Issues = "https://github.com/moda-labs/venn-cli/issues"
+
+[project.scripts]
+venn = "venn_cli.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.22",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: hits the live Venn API (requires VENN_API_KEY)",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/venn_cli"]

venn_cli-0.1.0/src/venn_cli/cli.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from venn_cli.client import VennClient
+from venn_cli import output
+
+
+def _load_env() -> None:
+    for p in [Path.cwd() / ".env", Path(__file__).resolve().parents[2] / ".env"]:
+        if p.exists():
+            load_dotenv(p)
+            return
+    load_dotenv()
+
+
+def _client(ctx: click.Context) -> VennClient:
+    return ctx.obj["client"]
+
+
+@click.group()
+@click.option("--api-key", envvar="VENN_API_KEY", help="Venn API key (or set VENN_API_KEY)")
+@click.option("--base-url", envvar="VENN_BASE_URL", default=None, help="Override API base URL")
+@click.option("--raw", is_flag=True, help="Output raw JSON instead of formatted tables")
+@click.version_option(package_name="venn-cli")
+@click.pass_context
+def main(ctx: click.Context, api_key: str | None, base_url: str | None, raw: bool) -> None:
+    """Venn ToolIQ CLI — discover, inspect, and execute tools."""
+    _load_env()
+    api_key = api_key or os.environ.get("VENN_API_KEY")
+    if not api_key:
+        click.echo("Error: VENN_API_KEY not set. Pass --api-key or add it to .env", err=True)
+        raise SystemExit(1)
+    kwargs = {"api_key": api_key}
+    if base_url:
+        kwargs["base_url"] = base_url
+    ctx.ensure_object(dict)
+    ctx.obj["client"] = VennClient(**kwargs)
+    ctx.obj["raw"] = raw
+
+
+# ---------------------------------------------------------------------------
+# venn tools
+# ---------------------------------------------------------------------------
+
+@main.group()
+def tools():
+    """Discover, inspect, and execute tools."""
+
+
+@tools.command("list")
+@click.option("--slug", "-s", help="Toolset slug (e.g. 'salesforce', 'gmail')")
+@click.option("--directory-id", "-d", help="Server directory UUID")
+@click.option("--instance-id", "-i", help="Server instance UUID")
+@click.pass_context
+def tools_list(ctx, slug, directory_id, instance_id):
+    """List tools for a server."""
+    if not any([slug, directory_id, instance_id]):
+        click.echo("Provide at least one of: --slug, --directory-id, --instance-id", err=True)
+        raise SystemExit(1)
+    data = _client(ctx).list_tools(slug=slug, directory_id=directory_id, instance_id=instance_id)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_tool_list(data.get("result", {}))
+
+
+@tools.command("search")
+@click.argument("query")
+@click.option("--limit", "-n", default=10, type=int, help="Max results")
+@click.option("--offset", default=0, type=int, help="Skip N results")
+@click.option("--min-score", default=0.3, type=float, help="Minimum similarity score")
+@click.option("--refresh", is_flag=True, help="Bypass cache")
+@click.pass_context
+def tools_search(ctx, query, limit, offset, min_score, refresh):
+    """Search tools by natural language query."""
+    data = _client(ctx).search_tools(query, limit=limit, offset=offset, min_score=min_score, refresh=refresh)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_search_results(data.get("result", {}))
+
+
+@tools.command("describe")
+@click.option("--server-id", "-s", required=True, help="Server identifier")
+@click.option("--tool-name", "-t", required=True, multiple=True, help="Tool name (repeatable)")
+@click.option("--refresh", is_flag=True, help="Bypass cache")
+@click.pass_context
+def tools_describe(ctx, server_id, tool_name, refresh):
+    """Get detailed schema for one or more tools."""
+    tools_list = [{"server_id": server_id, "tool_name": t} for t in tool_name]
+    data = _client(ctx).describe_tools(tools_list, refresh=refresh)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_tool_details(data.get("result", {}).get("results", []))
+
+
+@tools.command("execute")
+@click.option("--server-id", "-s", required=True, help="Server identifier")
+@click.option("--tool-name", "-t", required=True, help="Tool name")
+@click.option("--args", "-a", "tool_args", default=None, help="Tool arguments as JSON string")
+@click.option("--confirm", "do_confirm", is_flag=True, help="Auto-obtain confirmation token for write ops")
+@click.pass_context
+def tools_execute(ctx, server_id, tool_name, tool_args, do_confirm):
+    """Execute a tool."""
+    client = _client(ctx)
+    parsed_args = json.loads(tool_args) if tool_args else None
+
+    confirmation_token = None
+    if do_confirm:
+        confirm_data = client.confirm_write()
+        confirmation_token = confirm_data.get("result", {}).get("confirmation_token")
+
+    data = client.execute_tool(
+        server_id=server_id,
+        tool_name=tool_name,
+        tool_args=parsed_args,
+        confirmed=do_confirm,
+        confirmation_token=confirmation_token,
+    )
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_execute_result(data)
+
+
+@tools.command("confirm")
+@click.pass_context
+def tools_confirm(ctx):
+    """Get a confirmation token for write operations."""
+    data = _client(ctx).confirm_write()
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_confirm(data.get("result", {}))
+
+
+# ---------------------------------------------------------------------------
+# venn workflow
+# ---------------------------------------------------------------------------
+
+@main.group()
+def workflow():
+    """Execute code in a sandboxed environment."""
+
+
+@workflow.command("run")
+@click.option("--code", "-c", help="Python code to execute")
+@click.option("--file", "-f", "code_file", type=click.Path(exists=True), help="Read code from file")
+@click.option("--timeout", default=180, type=int, help="Max execution time in seconds")
+@click.option("--confirm", "do_confirm", is_flag=True, help="Obtain confirmation for write ops")
+@click.pass_context
+def workflow_run(ctx, code, code_file, timeout, do_confirm):
+    """Execute Python code in the Venn sandbox."""
+    if code_file:
+        code = Path(code_file).read_text()
+    if not code:
+        click.echo("Provide --code or --file", err=True)
+        raise SystemExit(1)
+
+    client = _client(ctx)
+    confirmation_token = None
+    if do_confirm:
+        confirm_data = client.confirm_write()
+        confirmation_token = confirm_data.get("result", {}).get("confirmation_token")
+
+    data = client.execute_workflow(
+        code=code,
+        timeout=timeout,
+        confirmed=do_confirm,
+        confirmation_token=confirmation_token,
+    )
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_execute_result(data)
+
+
+# ---------------------------------------------------------------------------
+# venn help
+# ---------------------------------------------------------------------------
+
+@main.command("help")
+@click.argument("action", required=False, type=click.Choice(
+    ["getting_started", "connector_help", "auth_helper", "list_servers"],
+    case_sensitive=False,
+))
+@click.option("--server-id", "-s", help="Server ID (required for auth_helper)")
+@click.option("--refresh", is_flag=True, help="Bypass cache")
+@click.pass_context
+def help_cmd(ctx, action, server_id, refresh):
+    """Get help, server status, or auth URLs."""
+    data = _client(ctx).help(action=action, server_id=server_id, refresh=refresh)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_help_result(data.get("result"))
+
+
+# ---------------------------------------------------------------------------
+# venn skills
+# ---------------------------------------------------------------------------
+
+@main.group()
+def skills():
+    """Manage executable skills."""
+
+
+@skills.command("upsert")
+@click.option("--file", "-f", "skill_file", required=True, type=click.Path(exists=True), help="Skill YAML file")
+@click.pass_context
+def skills_upsert(ctx, skill_file):
+    """Create or update a skill from a YAML file."""
+    content = Path(skill_file).read_text()
+    data = _client(ctx).upsert_skill(content)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.console.print("[green]Skill upserted successfully.[/green]")
+        if data.get("result"):
+            output.print_json(data["result"])
+
+
+# ---------------------------------------------------------------------------
+# venn history
+# ---------------------------------------------------------------------------
+
+@main.group()
+def history():
+    """View catalog and server revision history."""
+
+
+@history.command("toolset")
+@click.argument("toolset_key")
+@click.option("--limit", "-n", default=50, type=int, help="Max revisions")
+@click.option("--before", "before_version", default=None, type=int, help="Only show versions before this")
+@click.pass_context
+def history_toolset(ctx, toolset_key, limit, before_version):
+    """Show revision history for a toolset."""
+    data = _client(ctx).toolset_history(toolset_key, limit=limit, before_version=before_version)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_history(data.get("result", {}))
+
+
+@history.command("server")
+@click.argument("directory_id")
+@click.option("--limit", "-n", default=50, type=int, help="Max revisions")
+@click.option("--before", "before_version", default=None, type=int, help="Only show versions before this")
+@click.pass_context
+def history_server(ctx, directory_id, limit, before_version):
+    """Show revision history for a server instance."""
+    data = _client(ctx).server_history(directory_id, limit=limit, before_version=before_version)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_history(data.get("result", {}))