Release v2.2.0b1

Generated public mirror snapshot.

Author: Convilyn Release

.secrets.baseline

@@ -5,6 +5,46 @@ versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Docs
+
+- **QUICKSTART now starts at the actual step 0**: minting a `cvl_` developer
+  key via `ConvilynClient().register(...)` (the consumer `ck_` key does not
+  work on the author track, and there is no console UI for developer
+  registration yet). Also documents the server-less submission path for
+  authors who cannot host a public endpoint.
+- **Hosted-runtime error status corrected: 503, not 501.** Current platform
+  builds answer `503 HOSTED_NOT_AVAILABLE` (older builds used 501;
+  router-unmounted environments answer 404). `deploy --hosted`'s CLI hint now
+  matches both codes (TS parity), and the `deploy_hosted_runtime` docstring
+  and DEPLOYMENT.md no longer claim 501.
+
+## [2.2.0b1] — 2026-07-11
+
+### Added
+
+- **Server-less workflow submission.** `submit_workflow(workflow_spec)` no
+  longer requires `server_ids` — omit it (or pass an empty sequence) when
+  your spec orchestrates only platform built-in tools (OCR / document
+  parsing / analysis), the same shape every built-in goal-lane workflow
+  uses. No self-hosted HMAC tool server is needed for that class of
+  workflow, which unblocks edge/NAT authors who cannot expose a public
+  endpoint. The platform still enforces the `dev_{prefix}.` spec namespace
+  and warns on tool references it cannot resolve.
+
+## [2.1.1b5] — 2026-07-10
+
+### Fixed
+
+- **`WorkflowSpec` name/tool-count bounds are now actually enforced.**
+  2.1.1b4 added the check to the standalone `validate_workflow_spec()`
+  pre-submission validator, but `WorkflowSpec.compile()` (the path every
+  author and the community re-test actually exercises) never calls that
+  function, so a 200-character name or 30 tool references still compiled
+  successfully. The bound is now a `pydantic.Field` constraint on
+  `WorkflowBlueprint.name` / `MCPConfigModel.tools`, enforced immediately
+  at `use_tools()` / `compile()` time — the same place the TypeScript
+  author SDK enforces it.
+
 ## [2.1.1b4] — 2026-07-10
 
 ### Added

CHANGELOG.md

@@ -247,6 +247,11 @@ to self-host:
 convilyn-author deploy --hosted --region us-east-1   # preview
 ```
 
-This currently returns `501 HOSTED_NOT_AVAILABLE` in most accounts. The
+This currently returns `HOSTED_NOT_AVAILABLE` in most accounts (HTTP
+503 on current platform builds; older builds answered 501, and
+environments with the author-runtime router unmounted answer 404). The
 self-hosted targets above (Lambda / Fargate / VM), registered with
-`convilyn-author push`, are the supported paths for the beta.
+`convilyn-author push`, are the supported paths for the beta. If you
+cannot expose a public endpoint at all (edge device behind NAT) and
+your workflow only needs platform built-in tools, submit it server-less
+instead — see `submit_workflow` (no `server_ids`, no HMAC endpoint).

docs/DEPLOYMENT.md

@@ -16,12 +16,46 @@ Build tool servers + workflow specs for the Convilyn AI workflow platform.
 
 ## Quick Start
 
+### Step 0 — get a developer key (`cvl_`)
+
+The author track authenticates with a **developer** key (`cvl_` prefix) —
+your consumer key (`ck_`, from the web console) will NOT work here. Mint
+one by registering as a developer; there is no console UI for this yet:
+
+```python
+import asyncio
+from convilyn_sdk import ConvilynClient
+
+async def main() -> None:
+    result = await ConvilynClient().register(
+        email="you@example.com",
+        name="Your Name",
+        company="Optional Co.",
+    )
+    print(result["api_key"])   # cvl_… — shown ONCE, store it securely
+
+asyncio.run(main())
+```
+
+Export it as `CONVILYN_DEVELOPER_KEY` (see Environment Variables below).
+A 503 `REGISTRATION_STORE_UNAVAILABLE` response means the platform side
+is temporarily unavailable — retry later; it is not a problem with your
+request.
+
+### Step 1 — scaffold a tool server
+
 ```bash
 pip install convilyn-author
 convilyn-author init my-server
 cd my-server
 ```
 
+> **No public server?** If your workflow only orchestrates platform
+> built-in tools (OCR, document parsing, analysis), you can skip the
+> tool-server track entirely and submit the workflow spec server-less:
+> `await client.submit_workflow(spec)` — no `server_ids`, no HMAC
+> endpoint. See `submit_workflow` in `client.py`.
+
 Edit `server.py`:
 
 ```python

docs/README.md

@@ -11,4 +11,4 @@
 hardcoded constant in two places.
 """
 
-__version__ = "2.1.1b4"
+__version__ = "2.2.0b1"

src/convilyn_sdk/_version.py

@@ -314,7 +314,9 @@ async def _deploy() -> dict[str, Any]:
     try:
         result = asyncio.run(_deploy())
     except ConvilynClientError as e:
-        if e.status_code == 501:
+        # 503 = HOSTED_NOT_AVAILABLE on current platform builds; 501 kept
+        # for older builds (TS CLI applies the same pairing).
+        if e.status_code in (501, 503):
             click.echo(
                 f"Error: hosted runtime not yet available on this platform "
                 f"({e.detail}). Use `convilyn-author push --endpoint-url ...` "

src/convilyn_sdk/cli/main.py

@@ -22,6 +22,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any
 
 import httpx
@@ -225,21 +226,24 @@ async def deactivate_server(self, server_id: str) -> dict[str, Any]:
     async def submit_workflow(
         self,
         workflow_spec: dict[str, Any],
-        server_ids: list[str],
+        server_ids: Sequence[str] = (),
     ) -> dict[str, Any]:
         """Submit a workflow spec for validation and registration.
 
         Args:
             workflow_spec: Compiled workflow spec dict (from WorkflowSpec.compile()).
-            server_ids: List of server_ids whose tools this workflow uses.
+            server_ids: server_ids whose tools this workflow uses. Omit (or
+                pass an empty sequence) for a "server-less" spec that
+                orchestrates only platform built-in tools — no self-hosted
+                tool server required.
 
         Returns:
             Dict with workflow_id, spec_id, and status.
         """
         return await self._request(
             "POST",
             "/developers/workflows",
-            json={"workflow_spec": workflow_spec, "server_ids": server_ids},
+            json={"workflow_spec": workflow_spec, "server_ids": list(server_ids)},
         )
 
     async def list_workflows(self) -> list[dict[str, Any]]:
@@ -299,8 +303,10 @@ async def deploy_hosted_runtime(
         Raises:
             ConvilynClientError: backend failure. Backend code
                 ``HOSTED_NOT_AVAILABLE`` surfaces as a plain
-                ``ConvilynClientError`` with status 501 — callers can
-                catch it and fall back to ``submit_server`` + BYO
+                ``ConvilynClientError`` with status **503** (older
+                platform builds answered 501; environments where the
+                author-runtime router is unmounted answer 404) — callers
+                can catch it and fall back to ``submit_server`` + BYO
                 ``--endpoint-url`` if their CI needs a hard guarantee.
         """
         payload: dict[str, Any] = {

src/convilyn_sdk/client.py

@@ -129,6 +129,7 @@ class MCPConfigModel(BaseModel):
     )
     tools: list[str] = Field(
         default_factory=list,
+        max_length=20,
         description='Tool references in "server:tool" format',
     )
 
@@ -182,7 +183,7 @@ class WorkflowBlueprint(BaseModel):
 
     spec_id: str
     version: str
-    name: str
+    name: str = Field(max_length=80)
     description: str | None = None
     description_i18n: dict[str, str] | None = None
 

src/convilyn_sdk/workflow_types.py

@@ -296,6 +296,16 @@ async def test_submit_workflow(self):
         result = await client.submit_workflow({"spec_id": "x"}, ["srv_1"])
         assert result["workflow_id"] == "wf_1"
 
+    @pytest.mark.asyncio
+    async def test_submit_workflow_serverless_default(self):
+        """C3: server_ids may be omitted — a spec built on platform tools
+        needs no self-hosted server; the wire body carries an empty list."""
+        client = ConvilynClient(api_key="cvl_test", base_url="http://test")
+        client._request = AsyncMock(return_value={"workflow_id": "wf_1"})
+        await client.submit_workflow({"spec_id": "x"})
+        body = client._request.call_args.kwargs["json"]
+        assert body["server_ids"] == []
+
     @pytest.mark.asyncio
     async def test_list_workflows(self):
         client = ConvilynClient(api_key="cvl_test", base_url="http://test")

tests/unit/test_client.py

@@ -4,6 +4,9 @@
 import tempfile
 from pathlib import Path
 
+import pydantic
+import pytest
+
 from convilyn_sdk import ToolServer, WorkflowSpec
 
 
@@ -325,6 +328,23 @@ def test_compile_includes_mcp_when_tools_exist(self):
         assert "mcp_config" in compiled
         assert compiled["mcp_config"]["tools"] == ["s:t"]
 
+    def test_compile_accepts_name_at_max_length(self):
+        compiled = WorkflowSpec("x", name="x" * 80).compile()
+        assert len(compiled["name"]) == 80
+
+    def test_compile_rejects_name_over_max_length(self):
+        with pytest.raises(pydantic.ValidationError):
+            WorkflowSpec("x", name="x" * 81).compile()
+
+    def test_use_tools_accepts_max_tool_count(self):
+        spec = WorkflowSpec("x", name="X").use_tools(*[f"s:t{i}" for i in range(20)])
+        compiled = spec.compile()
+        assert len(compiled["mcp_config"]["tools"]) == 20
+
+    def test_use_tools_rejects_tool_count_over_max(self):
+        with pytest.raises(pydantic.ValidationError):
+            WorkflowSpec("x", name="X").use_tools(*[f"s:t{i}" for i in range(21)])
+
     def test_compile_full_workflow(self):
         server = _make_server()
         compiled = (