claritty-sdk 2.0.4__tar.gz → 2.2.0__tar.gz

{claritty_sdk-2.0.4 → claritty_sdk-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claritty-sdk
-Version: 2.0.4
+Version: 2.2.0
 Summary: Official SDK for building apps on the Claritty Platform
 Author: Claritty Platform
 License: MIT

{claritty_sdk-2.0.4 → claritty_sdk-2.2.0}/claritty_sdk/__init__.py

@@ -32,10 +32,11 @@ LLM client (existing)::
 
     from claritty_sdk.llm import get_llm_client
 
-The legacy decorators ``@workflow``, ``@uses_agent``, and
-``@trigger_template`` are deprecated. Workflows and triggers live in
-``app.yaml`` now; their decorators emit DeprecationWarning and will be
-removed in v3.
+Workflows and triggers are declarative — they live in ``app.yaml``
+(``intelligence.yaml``) and run on ``claritty_sdk.runtime``. The v1
+decorator/registry runtime (``@workflow``/``@uses_agent``/``@trigger_template``,
+``AgentRegistry``/``WorkflowRegistry``/``TriggerTemplateRegistry``,
+``WorkflowExecutor``) has been removed — there is one canonical (v2) runtime.
 """
 
 from . import llm
@@ -45,24 +46,9 @@ from .decorators import (
     get_registered_tool,
     list_registered_tool_ids,
     tool,
-    trigger_template,
-    uses_agent,
-    workflow,
-)
-from .enums import ExecutionMode, TriggerTemplateType
-from .executor import WorkflowExecutor  # deprecated; legacy apps still import
-from .graph import build_graph  # deprecated; legacy apps still import
-from .registry import (
-    AgentMeta,
-    AgentRegistry,
-    TriggerMeta,
-    TriggerTemplateRegistry,
-    WorkflowMeta,
-    WorkflowRegistry,
-    WorkflowStep,
 )
+from .graph import build_graph
 from .runtime import get_user_context, use_user_context
-from .trigger_manager import DynamicTriggerManager
 
 __all__ = [
     # v2 decorators
@@ -79,24 +65,11 @@ __all__ = [
     "list_registered_tool_ids",
     # llm
     "llm",
-    # legacy (deprecated; kept for one release)
-    "workflow",
-    "uses_agent",
-    "trigger_template",
-    "ExecutionMode",
-    "TriggerTemplateType",
-    "AgentRegistry",
-    "WorkflowRegistry",
-    "TriggerTemplateRegistry",
-    "AgentMeta",
-    "WorkflowMeta",
-    "WorkflowStep",
-    "TriggerMeta",
-    "WorkflowExecutor",
-    "DynamicTriggerManager",
+    # canvas graph (manifest-driven)
     "build_graph",
+    # per-request user context
     "get_user_context",
     "use_user_context",
 ]
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"

{claritty_sdk-2.0.4 → claritty_sdk-2.2.0}/claritty_sdk/cli_verify.py

@@ -4,6 +4,13 @@ Phase 5.8 — the single CLI that runs in both pre-commit hooks and CI.
 Hard-fails on any of:
 
   * Invalid ``app.yaml`` (shape or cross-reference)
+  * Manifest SEMANTIC errors that pydantic shape-validation can't see —
+    the same rules the platform applies at deploy
+    (``manifest-doc-validate.ts``): ``${steps.*}``/``${input.*}`` piping,
+    dotted-tool↔integration coupling, team-roster existence, and the
+    RUNNABLE + FIRED workflow invariant. So an app that passes
+    ``seed verify`` passes platform validation — no cryptic
+    post-upload "validation failed".
   * Invalid ``backend/custom/tools/*/impl.py`` (signature, decorator,
     banned imports, byte ceiling — same YAML rules the platform's
     ``CustomToolService`` uses)
@@ -14,7 +21,7 @@ Exit codes mirror ``cli_eval.py``::
 
     0  everything passes
     1  invalid manifest shape
-    2  manifest reference error (catalog id doesn't resolve)
+    2  manifest reference / semantic error
     3  setup error (no app.yaml, no catalog)
     4  secret-shaped string found
 
@@ -23,6 +30,7 @@ Usage::
     claritty seed verify                  # current dir
     claritty seed verify /path/to/seed    # explicit root
     claritty seed verify --catalog /path  # override catalog root
+    claritty seed verify --lenient        # skip the RUNNABLE+FIRED gate (mid-build)
     claritty seed verify --skip-secrets   # debug only — never use in CI
 """
 
@@ -259,6 +267,15 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         action="store_true",
         help="Skip the secret-shape scanner. NEVER use in CI.",
     )
+    parser.add_argument(
+        "--lenient",
+        action="store_true",
+        help=(
+            "Skip the strict RUNNABLE+FIRED workflow gate (an app must ship a "
+            "workflow that actually runs and is fired by a trigger). Use mid-build; "
+            "the deploy path runs strict."
+        ),
+    )
     args = parser.parse_args(argv)
 
     seed_root = Path(args.seed_root).resolve()
@@ -305,6 +322,36 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
 
         return 1 if isinstance(e, _Pyd) else 2
 
+    # 1b) manifest SEMANTIC rules — the platform's deploy-time gate, run
+    # LOCALLY so the developer sees every problem before upload (not a cryptic
+    # "validation failed" afterwards). Strict by default (matches the
+    # developer-submission gate); --lenient drops only the RUNNABLE+FIRED check.
+    import yaml as _yaml
+
+    from .manifest import validate_manifest_doc
+
+    try:
+        raw_doc = _yaml.safe_load(app_yaml.read_text("utf-8")) or {}
+    except _yaml.YAMLError as e:
+        _fail(f"{app_yaml.name} is not valid YAML: {e}")
+        return 1
+    sem = validate_manifest_doc(
+        raw_doc, require_runnable_workflow=not args.lenient
+    )
+    if not sem.ok:
+        for err in sem.errors:
+            _fail(err)
+        _info(
+            "These are the SAME checks the platform runs at deploy. Fix them here "
+            "and the deploy will pass. (Run with --lenient mid-build to drop only "
+            "the runnable+fired-workflow gate.)"
+        )
+        return 2
+    _ok(
+        f"manifest semantics validated"
+        + ("" if args.lenient else " (runnable + fired workflow)")
+    )
+
     # 2) custom-tool rules
     try:
         rules = load_rules(catalog_root)

{claritty_sdk-2.0.4 → claritty_sdk-2.2.0}/claritty_sdk/context.py

@@ -82,22 +82,11 @@ class BaseAgent:
     ``claritty_sdk.runtime.tool_loop.run_agent`` drives the LLM tool-use loop
     for you and validates the output against ``app.yaml#agents[].output``.
 
-    Do NOT implement ``execute()`` — that was the deprecated v1 contract; the
-    v2 runtime never calls it, so an agent that only defines ``execute()``
-    silently does nothing. ``run_agent`` raises if an agent has no
-    ``system_prompt``/``prompt_file``.
+    Do NOT implement ``execute()`` — that was the v1 contract and has been
+    removed. Define a ``system_prompt`` (or ``prompt_file``); the v2 runtime's
+    ``run_agent`` raises if an agent has neither.
     """
 
-    # Deprecated v1 entrypoint, kept only so the inherited symbol exists. The v2
-    # tool-use loop never calls this; defining your own execute() is rejected at
-    # build (materializer) and at boot (bootstrap).
-    async def execute(self, context: "AgentContext") -> "AgentResult":  # pragma: no cover - deprecated
-        raise NotImplementedError(
-            "execute() is the deprecated v1 agent contract and is never called "
-            "by the v2 runtime. Define a `system_prompt` (or prompt_file) "
-            "instead; claritty_sdk.runtime.tool_loop.run_agent drives the loop."
-        )
-
 
 class GenericAgent(BaseAgent):
     """Pure-YAML agent. The runtime binds this when an `app.yaml` agent declares

claritty_sdk-2.2.0/claritty_sdk/decorators.py

@@ -0,0 +1,116 @@
+"""SDK decorators.
+
+In the v2 (manifest-first) SDK, decorators are **binders**: they attach
+a Python symbol to an ``app.yaml`` entry by id. They no longer carry
+schema, integrations, model, timeout, or any other data the manifest
+declares — that data lives in ``app.yaml`` and is loaded by
+``claritty_sdk.runtime.bootstrap``.
+
+Two decorators:
+
+- ``@agent(id="...")`` on a ``BaseAgent`` subclass.
+- ``@tool(id="...")`` on a plain function ``(input: dict, ctx: ToolCtx) -> dict``.
+
+Workflows and triggers are declarative — they live in ``app.yaml#workflows``
+and ``app.yaml#triggers`` and run on ``claritty_sdk.runtime``. The v1
+``@workflow``/``@uses_agent``/``@trigger_template`` decorators (and the
+``AgentRegistry``/``WorkflowRegistry``/``TriggerTemplateRegistry`` they fed)
+have been removed.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any, Callable, Dict, List, Optional, Type
+
+
+# ---------------------------------------------------------------------------
+# @agent and @tool — manifest-first binders
+# ---------------------------------------------------------------------------
+
+
+def agent(
+    *,
+    id: str,
+    # Legacy kwargs are still accepted (and ignored) so an app that hasn't
+    # stripped them from `@agent(...)` keeps importing — the data lives in
+    # app.yaml#agents. A manifest-first agent should pass only `id=`.
+    name: Optional[str] = None,
+    description: str = "",
+    category: Optional[str] = None,
+    inputs: Optional[Dict[str, Any]] = None,
+    outputs: Optional[Dict[str, Any]] = None,
+    timeout: Optional[int] = None,
+    integrations: Optional[List[Any]] = None,
+    **_extra: Any,
+) -> Callable[[Type], Type]:
+    """Bind a Python class to ``app.yaml#agents[id=...]``.
+
+    The class should subclass ``BaseAgent`` and expose ``system_prompt: str``
+    (or ``prompt_file``) and optionally ``before(ctx)`` / ``after(ctx, output)``
+    / ``fallback(ctx)`` hooks. The Anthropic tool-use loop is run by
+    ``claritty_sdk.runtime.tool_loop``; the v2 runtime loads the handler class
+    from the manifest's ``handler:`` field, so no registry is involved.
+    """
+
+    def decorate(cls: Type) -> Type:
+        # Lightweight marker for introspection/debugging only — the v2 runtime
+        # resolves handlers from the manifest, not from this attribute.
+        cls.__clarity_agent__ = {"id": id}  # type: ignore[attr-defined]
+        return cls
+
+    return decorate
+
+
+# Tool binding: minimalist registry kept here so the tool-use loop and the
+# workflow engine can dispatch ``tool_use`` blocks to the bound function.
+_TOOLS: Dict[str, Callable[..., Any]] = {}
+
+
+def tool(*, id: str, **_extra: Any) -> Callable[[Callable], Callable]:
+    """Bind a Python function to ``app.yaml#tools[id=...]``.
+
+    The function must take ``(input: dict, ctx: ToolCtx) -> dict`` (or
+    ``-> Awaitable[dict]`` — the runtime awaits if needed). The manifest
+    declares the input/output schema and the SDK validates both at
+    invocation time.
+
+    Example::
+
+        from claritty_sdk import tool, ToolCtx
+
+        @tool(id="db.save_task")
+        def save_task(input: dict, ctx: ToolCtx) -> dict:
+            task = ctx.db.tasks.insert(user_id=ctx.user_id, **input)
+            return {"task_id": task.id}
+    """
+
+    def decorate(fn: Callable) -> Callable:
+        if id in _TOOLS and _TOOLS[id] is not fn:
+            # Re-registration during dev (hot reload) is fine; warn so
+            # collisions across modules are visible.
+            warnings.warn(
+                f"@tool(id={id!r}) is being re-registered — earlier "
+                "binder is overwritten.",
+                stacklevel=2,
+            )
+        fn.__clarity_tool_id__ = id  # type: ignore[attr-defined]
+        _TOOLS[id] = fn
+        return fn
+
+    return decorate
+
+
+def get_registered_tool(tool_id: str) -> Optional[Callable[..., Any]]:
+    """Look up a tool handler by id. Used by the workflow engine and the
+    tool-use loop to dispatch ``tool_use`` blocks."""
+    return _TOOLS.get(tool_id)
+
+
+def list_registered_tool_ids() -> List[str]:
+    return sorted(_TOOLS.keys())
+
+
+def _clear_tool_registry() -> None:
+    """Test hook — not part of the public surface."""
+    _TOOLS.clear()

{claritty_sdk-2.0.4 → claritty_sdk-2.2.0}/claritty_sdk/graph.py

@@ -11,8 +11,6 @@ from __future__ import annotations
 import re
 from typing import Any, Dict, List, Optional, Set
 
-from .enums import ExecutionMode
-from .registry import AgentRegistry, TriggerTemplateRegistry, WorkflowRegistry
 
 GRAPH_VERSION = 1
 
@@ -105,6 +103,50 @@ def _resource_nodes_and_edges(
                     "data": {"kind": "tool"},
                 }
             )
+
+    # Tools that broker an integration server-side (e.g. a `publish` tool that
+    # posts through `linkedin`). Surface the integration wired to the tool node so
+    # tool-only automations show what they connect to — mirrors the agent loop
+    # above. The tool node is emitted here if no agent already declared it.
+    for t in manifest.tools or []:
+        tool_ints = list(getattr(t, "integrations", None) or [])
+        if not tool_ints:
+            continue
+        t_node = _tool_node_id(t.id)
+        if t.id not in seen_tool:
+            seen_tool.add(t.id)
+            nodes.append(
+                {
+                    "id": t_node,
+                    "type": "tool",
+                    "name": t.id,
+                    "data": {
+                        "toolId": t.id,
+                        "source": getattr(t, "source", None),
+                        "handler": getattr(t, "handler", None),
+                        "integrations": tool_ints,
+                    },
+                }
+            )
+        for iid in tool_ints:
+            if iid not in seen_int:
+                seen_int.add(iid)
+                nodes.append(
+                    {
+                        "id": _integration_node_id(iid),
+                        "type": "integration",
+                        "name": iid,
+                        "data": {"integrationId": iid},
+                    }
+                )
+            edges.append(
+                {
+                    "id": f"{t_node}->{_integration_node_id(iid)}",
+                    "source": t_node,
+                    "target": _integration_node_id(iid),
+                    "data": {"kind": "integration"},
+                }
+            )
     return nodes, edges
 
 
@@ -280,9 +322,12 @@ def build_graph_from_manifest(manifest: Any) -> Dict[str, Any]:
 
 
 def build_graph() -> Dict[str, Any]:
-    """Build the graph contract. Prefers the loaded v2 manifest (which carries
-    YAML workflows/triggers + each agent's tools/integrations); falls back to
-    the v1 decorator registries for legacy apps."""
+    """Build the canvas graph contract from the loaded v2 manifest (which
+    carries YAML workflows/triggers + each agent's tools/integrations).
+
+    Manifest-first is the only contract: if no app has been booted (no manifest
+    loaded), there is nothing to graph, so return an empty graph rather than
+    crashing the discovery endpoint."""
 
     # Lazy import to avoid a circular import at module load (bootstrap imports
     # the manifest + engine, not graph).
@@ -295,106 +340,10 @@ def build_graph() -> Dict[str, Any]:
     if boot is not None and getattr(boot, "manifest", None) is not None:
         return build_graph_from_manifest(boot.manifest)
 
-    nodes: List[Dict[str, Any]] = []
-    edges: List[Dict[str, Any]] = []
-
-    for a in AgentRegistry.list_agents():
-        # Normalize integrations (AgentMeta stores them as objects with an id).
-        raw_ints = getattr(a, "integrations", None) or []
-        ints = [
-            (i if isinstance(i, str) else getattr(i, "id", None) or getattr(i, "service", None))
-            for i in raw_ints
-        ]
-        nodes.append(
-            {
-                "id": _agent_node_id(a.id),
-                "type": "agent",
-                "name": a.name,
-                "data": {
-                    "agentId": a.id,
-                    "category": a.category,
-                    "description": a.description,
-                    "inputs": a.inputs,
-                    "outputs": a.outputs,
-                    "tools": list(getattr(a, "tools", None) or []),
-                    "integrations": [i for i in ints if i],
-                },
-            }
-        )
-
-    for t in TriggerTemplateRegistry.list_templates():
-        nodes.append(
-            {
-                "id": _trigger_node_id(t.id),
-                "type": "trigger",
-                "name": t.name,
-                "data": {
-                    "triggerId": t.id,
-                    "templateType": getattr(t.template_type, "value", t.template_type),
-                    "workflowId": t.workflow_id,
-                    "category": t.category,
-                },
-            }
-        )
-
-    workflows_out: List[Dict[str, Any]] = []
-    for wf in WorkflowRegistry.list_workflows():
-        steps = wf.steps or []
-        workflows_out.append(
-            {
-                "id": wf.id,
-                "name": wf.name,
-                "executionMode": getattr(wf.execution_mode, "value", wf.execution_mode),
-                "steps": [
-                    {"agentId": s.agent_id, "outputKey": s.output_key, "inputFrom": s.input_from}
-                    for s in steps
-                ],
-            }
-        )
-
-        # Agent→agent edges. For SEQUENTIAL workflows, chain consecutive steps
-        # (honoring explicit input_from); PARALLEL workflows have no inter-agent
-        # edges (only the trigger fans into each agent).
-        sequential = wf.execution_mode == ExecutionMode.SEQUENTIAL
-        prev_node = None
-        for step in steps:
-            cur = _agent_node_id(step.agent_id)
-            src = None
-            if step.input_from:
-                match = next((x for x in steps if x.output_key == step.input_from), None)
-                if match:
-                    src = _agent_node_id(match.agent_id)
-            elif sequential and prev_node:
-                src = prev_node
-            if src and src != cur:
-                edges.append(
-                    {
-                        "id": f"{wf.id}:{src}->{cur}",
-                        "source": src,
-                        "target": cur,
-                        "data": {"workflowId": wf.id},
-                    }
-                )
-            prev_node = cur
-
-        # Trigger→entry-agent edges.
-        if steps:
-            entry = _agent_node_id(steps[0].agent_id)
-            for t in TriggerTemplateRegistry.list_templates():
-                if t.workflow_id == wf.id:
-                    edges.append(
-                        {
-                            "id": f"trigger:{t.id}->{entry}",
-                            "source": _trigger_node_id(t.id),
-                            "target": entry,
-                            "data": {"workflowId": wf.id, "trigger": True},
-                        }
-                    )
-
     return {
         "version": GRAPH_VERSION,
-        "nodes": nodes,
-        "edges": edges,
-        "workflows": workflows_out,
-        "source": "runtime",
+        "nodes": [],
+        "edges": [],
+        "workflows": [],
+        "source": "manifest",
     }

{claritty_sdk-2.0.4 → claritty_sdk-2.2.0}/claritty_sdk/llm.py

@@ -168,6 +168,7 @@ class LlmClient:
         max_tokens: Optional[int] = None,
         system: Optional[str] = None,
         extra_headers: Optional[dict] = None,
+        thinking: Optional[dict] = None,
     ) -> "ChatToolsResult":
         """OpenAI-Chat-Completions tool calling.
 
@@ -181,7 +182,9 @@ class LlmClient:
         the proxy uses to enforce a per-run $ ceiling and surface a 402
         ``WORKFLOW_BUDGET_EXCEEDED`` envelope when exceeded.
         """
-        body = self._build_body(messages, temperature, max_tokens, system, stream=False)
+        body = self._build_body(
+            messages, temperature, max_tokens, system, stream=False, thinking=thinking
+        )
         body["tools"] = tools
         if tool_choice is not None:
             body["tool_choice"] = tool_choice
@@ -272,6 +275,7 @@ class LlmClient:
         system: Optional[str],
         *,
         stream: bool,
+        thinking: Optional[dict] = None,
     ) -> dict:
         # Merge the active agent's user context (the platform's per-agent
         # "how to do your job" instructions) into the system prompt so it
@@ -304,7 +308,12 @@ class LlmClient:
                 out["name"] = m["name"]
             msgs.append(out)
         body: dict = {"model": self.model, "messages": msgs}
-        if temperature is not None:
+        if thinking is not None:
+            # Anthropic extended thinking. The metered proxy forwards this to the
+            # Anthropic `thinking` param. Anthropic requires temperature unset
+            # (=1) while thinking is on, so we DON'T send temperature here.
+            body["thinking"] = thinking
+        elif temperature is not None:
             body["temperature"] = temperature
         if max_tokens is not None:
             body["max_tokens"] = max_tokens
@@ -365,7 +374,29 @@ def _raise_for_status(res: httpx.Response) -> None:
     if res.is_success:
         return
     try:
-        payload = res.json()
+        payload: Any = res.json()
     except Exception:
-        payload = res.text
+        text = res.text or ""
+        # A non-JSON body means the response did NOT come from the clarity-api
+        # proxy (which always returns a JSON error envelope). The overwhelmingly
+        # common cause is a proxy URL pointing at the wrong host — e.g. the
+        # frontend (app.claritty.ai / :3000) instead of the API
+        # (api.claritty.ai / :4000) — so `/api/v1/chat/completions` 404/500s as
+        # an HTML page. Turn that opaque HTML dump into an actionable error that
+        # names the exact URL and the likely fix.
+        looks_like_html = "<html" in text[:512].lower() or "<!doctype" in text[:512].lower()
+        if looks_like_html:
+            payload = {
+                "message": (
+                    f"the LLM proxy at {res.request.url} returned an HTML "
+                    f"{res.status_code} page, not a JSON error — this host is "
+                    "almost certainly NOT the clarity-api proxy. Check "
+                    "CLARITTY_LLM_PROXY_URL / CLARITTY_PLATFORM_URL: it must be "
+                    "the API host (e.g. https://api.claritty.ai), not the "
+                    "frontend (app.claritty.ai) or a local web port (:3000)."
+                ),
+                "non_json_body": text[:500],
+            }
+        else:
+            payload = text
     raise LlmProxyError(res.status_code, payload)