archastro.platform.v1.resources.workflows

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 1afd297ab2c6
  4
  5from __future__ import annotations
  6
  7import builtins
  8from typing import Any, TypedDict
  9
 10from pydantic import BaseModel, Field
 11
 12from ...runtime.http_client import HttpClient, SyncHttpClient
 13from ...types.common import Command, NodeType
 14from ...types.expressions import ExpressionResult, ExpressionValidation
 15from ...types.graph import GraphValidation
 16
 17
 18class ExpressionRunInput(TypedDict, total=False):
 19    "Run a workflow expression"
 20
 21    expression: str | None
 22    "The workflow expression source to evaluate. Defaults to an empty string."
 23    scope: dict[str, Any] | None
 24    "Key-value map of variables available to the expression at evaluation time. Defaults to an empty map."
 25
 26
 27class ExpressionValidateInput(TypedDict, total=False):
 28    "Validate a workflow expression"
 29
 30    expression: str | None
 31    "The workflow expression source to validate. Defaults to an empty string."
 32
 33
 34class GraphValidateInput(TypedDict):
 35    "Validate a workflow graph"
 36
 37    graph: dict[str, Any]
 38    "Complete workflow graph definition to validate, containing node and edge declarations."
 39
 40
 41class WorkflowRunInput(TypedDict, total=False):
 42    "Execute a workflow node or graph"
 43
 44    context: dict[str, Any] | None
 45    "Additional execution context made available to workflow nodes at runtime. Merged with the authenticated viewer context set by the platform. Defaults to an empty object if omitted."
 46    env: dict[str, Any] | None
 47    "Evaluator environment variables injected into expression contexts during execution. The platform automatically merges developer-tier runtime env vars before evaluation. Defaults to an empty object if omitted."
 48    graph: dict[str, Any] | None
 49    "A complete workflow graph to execute. Must be an object conforming to the `WorkflowGraph` schema (keys: `start_node`, `nodes`, etc.). Mutually exclusive with `node` supply exactly one."
 50    node: dict[str, Any] | None
 51    "A single workflow node to execute in isolation. Must be an object with at minimum a `type` key identifying the node kind, plus any node-specific configuration values. Mutually exclusive with `graph` supply exactly one."
 52    payload: dict[str, Any] | None
 53    "Arbitrary input data passed into the workflow as the initial payload. Defaults to an empty object if omitted."
 54    run_as_agent: str | None
 55    "Agent ID (`agt_...`) of the agent to impersonate for the execution. When set, workflow nodes run with this agent as the acting principal instead of the authenticated developer. The agent must belong to the current app. Mutually exclusive with `run_as_user`. `null` by default (runs as the authenticated developer)."
 56    run_as_user: str | None
 57    "User ID (`usr_...`) of the user to impersonate for the execution. When set, workflow nodes run with this user as the acting principal instead of the authenticated developer. Mutually exclusive with `run_as_agent`. `null` by default (runs as the authenticated developer)."
 58
 59
 60class EventSampleResponse(BaseModel):
 61    """
 62    Successful response
 63    """
 64
 65    sample: dict[str, Any] = Field(..., description="Representative event payload.")
 66
 67
 68class WorkflowRunResponse(BaseModel):
 69    """
 70    Successful response
 71    """
 72
 73    context: dict[str, Any] | None = Field(default=None, description="Execution context.")
 74    env: dict[str, Any] | None = Field(default=None, description="Execution environment.")
 75    error: str | None = Field(default=None, description="Execution error message.")
 76    files: list[dict[str, Any]] | None = Field(
 77        default=None, description="Files created during graph execution."
 78    )
 79    log: list[str] | None = Field(default=None, description="Node execution log lines.")
 80    nextNodeId: str | None = Field(
 81        default=None, description="Next node ID, when execution yielded."
 82    )
 83    output: Any | None = Field(default=None, description="Node output or graph output lines.")
 84    payload: Any | None = Field(
 85        default=None, description="Final or node-produced JSON-safe payload."
 86    )
 87    records: list[dict[str, Any]] | None = Field(
 88        default=None, description="Graph execution records."
 89    )
 90    startNodeId: str | None = Field(default=None, description="Graph start node ID.")
 91    status: str | None = Field(default=None, description="Graph execution status.")
 92    wait: dict[str, Any] | None = Field(default=None, description="Yielded wait state.")
 93
 94
 95class AsyncEventResource:
 96    def __init__(self, http: HttpClient):
 97        self._http = http
 98
 99    async def sample(self, name: str) -> EventSampleResponse:
100        """
101        Retrieve a sample event payload
102        Returns a representative sample payload for the specified workflow event type.
103        Use this to inspect the structure of an event before configuring a workflow
104        trigger or building an event handler.
105        Requires a valid developer session. Returns 404 if the event name is not
106        registered in the platform event catalog.
107
108        Args:
109            name: Fully-qualified event type name registered in the catalog, e.g. `"thread.created"`. Returns 404 if the name is not recognized.
110
111        Returns:
112            Successful response
113        """
114        return await self._http.request(
115            f"/api/v1/workflows/events/{name}/sample",
116            response_type=EventSampleResponse,
117        )
118
119
120class AsyncExpressionResource:
121    def __init__(self, http: HttpClient):
122        self._http = http
123
124    async def run(self, input: ExpressionRunInput) -> ExpressionResult:
125        """
126        Run a workflow expression
127        Evaluates a single workflow expression string against a caller-supplied variable scope
128        and returns the computed result. Use this endpoint to test and iterate on expressions
129        during workflow development before embedding them in a workflow graph.
130        The expression is evaluated synchronously. If evaluation fails (syntax error, runtime
131        exception, or type mismatch), the endpoint returns a 422 with a human-readable reason
132        rather than a 200 with an error payload. Successful responses always include any
133        `println` output captured during evaluation.
134        Requires an authenticated developer session. The expression runs in an isolated
135        context and cannot access platform resources beyond what you supply in `scope`.
136
137        Args:
138            input: Request body.
139            input.expression: The workflow expression source to evaluate. Defaults to an empty string.
140            input.scope: Key-value map of variables available to the expression at evaluation time. Defaults to an empty map.
141
142        Returns:
143            The result of evaluating the expression, including any captured print output.
144        """
145        return await self._http.request(
146            "/api/v1/workflows/expressions/run",
147            method="POST",
148            body=input,
149            response_type=ExpressionResult,
150        )
151
152    async def validate(self, input: ExpressionValidateInput) -> ExpressionValidation:
153        """
154        Validate a workflow expression
155        Parses and statically analyses a workflow expression string without executing it.
156        Returns structured findings, inferred symbol types, and any warnings so that editors
157        and build-time tooling can surface diagnostics before the expression is used in a
158        live workflow.
159        The response always includes an `ok` flag indicating whether the validation call
160        itself succeeded, and a separate `valid` flag indicating whether the expression
161        passed analysis. A 200 is returned regardless of whether the expression is valid;
162        a 401 is returned if the caller is not authenticated.
163        Requires an authenticated developer session.
164
165        Args:
166            input: Request body.
167            input.expression: The workflow expression source to validate. Defaults to an empty string.
168
169        Returns:
170            Validation outcome including parse errors, warnings, symbol types, and structured editor diagnostics.
171        """
172        return await self._http.request(
173            "/api/v1/workflows/expressions/validate",
174            method="POST",
175            body=input,
176            response_type=ExpressionValidation,
177        )
178
179
180class AsyncGraphResource:
181    def __init__(self, http: HttpClient):
182        self._http = http
183
184    async def validate(self, input: GraphValidateInput) -> GraphValidation:
185        """
186        Validate a workflow graph
187        Submits a workflow graph definition for static analysis and returns a
188        structured validation report. The graph is checked for structural correctness
189        (valid node and edge references) and then analyzed for logical issues such as
190        unreachable nodes, dead-end paths, and cycles.
191        This endpoint is non-destructive it does not persist any data. Use it
192        during development to surface problems with a graph definition before saving
193        or executing it. Requires developer-level authentication.
194
195        Args:
196            input: Request body.
197            input.graph: Complete workflow graph definition to validate, containing node and edge declarations.
198
199        Returns:
200            Validation report describing whether the graph is structurally sound and any findings from static analysis.
201        """
202        return await self._http.request(
203            "/api/v1/workflows/graph/validate",
204            method="POST",
205            body=input,
206            response_type=GraphValidation,
207        )
208
209
210class AsyncNodeTypeResource:
211    def __init__(self, http: HttpClient):
212        self._http = http
213
214    async def list(self) -> builtins.list[NodeType]:
215        """
216        List workflow node types
217        Returns an array of all node type definitions registered with the workflow host. Node
218        types describe the available building blocks for constructing workflow graphs, including
219        each type's label, category, color, and configurable field definitions.
220        This endpoint requires a valid authenticated session. It does not support pagination
221        all registered node types are returned in a single response. The list reflects the
222        node types available at the time of the request; types are registered at startup and
223        do not change at runtime.
224
225        Returns:
226            Array of all registered workflow node type definitions.
227        """
228        return await self._http.request(
229            "/api/v1/workflows/node_types",
230            response_type=list[NodeType],
231        )
232
233    async def get(self, node_type: str) -> NodeType:
234        """
235        Retrieve a workflow node type
236        Returns the full definition for a single workflow node type, identified by its
237        string identifier. The response includes the node type's label, description, category,
238        display properties, and the complete list of configurable field definitions.
239        Returns 404 if no node type with the given identifier is registered. This endpoint
240        requires a valid authenticated session.
241
242        Args:
243            node_type: Identifier of the node type to retrieve, e.g. `"http_request"` or `"conditional"`.
244
245        Returns:
246            The requested workflow node type definition.
247        """
248        return await self._http.request(
249            f"/api/v1/workflows/node_types/{node_type}",
250            response_type=NodeType,
251        )
252
253
254class AsyncSampleResource:
255    def __init__(self, http: HttpClient):
256        self._http = http
257
258    async def list(self) -> dict[str, str]:
259        """
260        Retrieve a sample workflow graph
261        Returns a minimal, runnable `WorkflowGraph` YAML document that illustrates the
262        structure of a workflow graph. Use this as a starting point when building or
263        testing your own workflow definitions.
264        The response is returned as plain YAML (`application/x-yaml`) rather than JSON.
265        The sample graph includes a trigger node, a transform node, and an event-emit
266        node wired together in sequence.
267
268        Returns:
269            Minimal runnable WorkflowGraph YAML document.
270        """
271        return await self._http.request_raw("/api/v1/workflows/sample")
272
273
274class AsyncWorkflowResource:
275    def __init__(self, http: HttpClient):
276        self._http = http
277        self.events = AsyncEventResource(http)
278        self.expressions = AsyncExpressionResource(http)
279        self.graph = AsyncGraphResource(http)
280        self.node_types = AsyncNodeTypeResource(http)
281        self.sample = AsyncSampleResource(http)
282
283    async def commands(self) -> list[Command]:
284        """
285        List available workflow commands
286        Returns the full set of workflow commands registered with the workflow host.
287        Commands represent discrete operations that a workflow node can invoke each
288        carries its own input and output schemas used by the workflow builder.
289        This endpoint requires a valid developer session. The list is not paginated;
290        all registered commands are returned in a single response.
291
292        Returns:
293            Array of all registered workflow command definitions.
294        """
295        return await self._http.request("/api/v1/workflows/commands", response_type=list[Command])
296
297    async def llm_txt(self) -> dict[str, str]:
298        """
299        Retrieve the workflow-authoring LLM prompt
300        Returns the plain-text system prompt used by workflow-authoring assistants.
301        The prompt is rendered from the registered node types and commands so its
302        authoring guidance stays synchronized with the running platform.
303
304        Returns:
305            Plain-text system prompt for workflow-authoring assistants.
306        """
307        return await self._http.request_raw("/api/v1/workflows/llm.txt")
308
309    async def run(self, input: WorkflowRunInput) -> WorkflowRunResponse:
310        """
311        Execute a workflow node or graph
312        Executes a single workflow node or a complete workflow graph and returns the result.
313        Supply either `node` (to run one node in isolation) or `graph` (to execute a full
314        directed graph); the two parameters are mutually exclusive and exactly one must be
315        provided.
316        The authenticated developer is used as the default workflow principal for entitlement
317        checks on billable operations such as LLM calls. Supply `run_as_user` or
318        `run_as_agent` to override the acting identity for the execution at most one
319        override may be set per request. Overrides are subject to the caller's
320        delegation permissions, the same ones `/scripts/run` applies: app secret keys
321        and developer tokens may run as any user or agent in the app; other callers may
322        run as themselves, and as an agent they own (org admins as any agent in their
323        org). A refused override returns 403 before anything runs.
324        Execution errors are logged to the activity feed under the acting identity so they
325        appear alongside automation-driven workflow errors in operator dashboards. A 422
326        response is returned when execution fails; the response body includes the error
327        message and any partial records produced before the failure.
328
329        Args:
330            input: Request body.
331            input.context: Additional execution context made available to workflow nodes at runtime. Merged with the authenticated viewer context set by the platform. Defaults to an empty object if omitted.
332            input.env: Evaluator environment variables injected into expression contexts during execution. The platform automatically merges developer-tier runtime env vars before evaluation. Defaults to an empty object if omitted.
333            input.graph: A complete workflow graph to execute. Must be an object conforming to the `WorkflowGraph` schema (keys: `start_node`, `nodes`, etc.). Mutually exclusive with `node` supply exactly one.
334            input.node: A single workflow node to execute in isolation. Must be an object with at minimum a `type` key identifying the node kind, plus any node-specific configuration values. Mutually exclusive with `graph` supply exactly one.
335            input.payload: Arbitrary input data passed into the workflow as the initial payload. Defaults to an empty object if omitted.
336            input.run_as_agent: Agent ID (`agt_...`) of the agent to impersonate for the execution. When set, workflow nodes run with this agent as the acting principal instead of the authenticated developer. The agent must belong to the current app. Mutually exclusive with `run_as_user`. `null` by default (runs as the authenticated developer).
337            input.run_as_user: User ID (`usr_...`) of the user to impersonate for the execution. When set, workflow nodes run with this user as the acting principal instead of the authenticated developer. Mutually exclusive with `run_as_agent`. `null` by default (runs as the authenticated developer).
338
339        Returns:
340            Successful response
341        """
342        return await self._http.request(
343            "/api/v1/workflows/run",
344            method="POST",
345            body=input,
346            response_type=WorkflowRunResponse,
347        )
348
349
350class EventResource:
351    def __init__(self, http: SyncHttpClient):
352        self._http = http
353
354    def sample(self, name: str) -> EventSampleResponse:
355        """
356        Retrieve a sample event payload
357        Returns a representative sample payload for the specified workflow event type.
358        Use this to inspect the structure of an event before configuring a workflow
359        trigger or building an event handler.
360        Requires a valid developer session. Returns 404 if the event name is not
361        registered in the platform event catalog.
362
363        Args:
364            name: Fully-qualified event type name registered in the catalog, e.g. `"thread.created"`. Returns 404 if the name is not recognized.
365
366        Returns:
367            Successful response
368        """
369        return self._http.request(
370            f"/api/v1/workflows/events/{name}/sample",
371            response_type=EventSampleResponse,
372        )
373
374
375class ExpressionResource:
376    def __init__(self, http: SyncHttpClient):
377        self._http = http
378
379    def run(self, input: ExpressionRunInput) -> ExpressionResult:
380        """
381        Run a workflow expression
382        Evaluates a single workflow expression string against a caller-supplied variable scope
383        and returns the computed result. Use this endpoint to test and iterate on expressions
384        during workflow development before embedding them in a workflow graph.
385        The expression is evaluated synchronously. If evaluation fails (syntax error, runtime
386        exception, or type mismatch), the endpoint returns a 422 with a human-readable reason
387        rather than a 200 with an error payload. Successful responses always include any
388        `println` output captured during evaluation.
389        Requires an authenticated developer session. The expression runs in an isolated
390        context and cannot access platform resources beyond what you supply in `scope`.
391
392        Args:
393            input: Request body.
394            input.expression: The workflow expression source to evaluate. Defaults to an empty string.
395            input.scope: Key-value map of variables available to the expression at evaluation time. Defaults to an empty map.
396
397        Returns:
398            The result of evaluating the expression, including any captured print output.
399        """
400        return self._http.request(
401            "/api/v1/workflows/expressions/run",
402            method="POST",
403            body=input,
404            response_type=ExpressionResult,
405        )
406
407    def validate(self, input: ExpressionValidateInput) -> ExpressionValidation:
408        """
409        Validate a workflow expression
410        Parses and statically analyses a workflow expression string without executing it.
411        Returns structured findings, inferred symbol types, and any warnings so that editors
412        and build-time tooling can surface diagnostics before the expression is used in a
413        live workflow.
414        The response always includes an `ok` flag indicating whether the validation call
415        itself succeeded, and a separate `valid` flag indicating whether the expression
416        passed analysis. A 200 is returned regardless of whether the expression is valid;
417        a 401 is returned if the caller is not authenticated.
418        Requires an authenticated developer session.
419
420        Args:
421            input: Request body.
422            input.expression: The workflow expression source to validate. Defaults to an empty string.
423
424        Returns:
425            Validation outcome including parse errors, warnings, symbol types, and structured editor diagnostics.
426        """
427        return self._http.request(
428            "/api/v1/workflows/expressions/validate",
429            method="POST",
430            body=input,
431            response_type=ExpressionValidation,
432        )
433
434
435class GraphResource:
436    def __init__(self, http: SyncHttpClient):
437        self._http = http
438
439    def validate(self, input: GraphValidateInput) -> GraphValidation:
440        """
441        Validate a workflow graph
442        Submits a workflow graph definition for static analysis and returns a
443        structured validation report. The graph is checked for structural correctness
444        (valid node and edge references) and then analyzed for logical issues such as
445        unreachable nodes, dead-end paths, and cycles.
446        This endpoint is non-destructive it does not persist any data. Use it
447        during development to surface problems with a graph definition before saving
448        or executing it. Requires developer-level authentication.
449
450        Args:
451            input: Request body.
452            input.graph: Complete workflow graph definition to validate, containing node and edge declarations.
453
454        Returns:
455            Validation report describing whether the graph is structurally sound and any findings from static analysis.
456        """
457        return self._http.request(
458            "/api/v1/workflows/graph/validate",
459            method="POST",
460            body=input,
461            response_type=GraphValidation,
462        )
463
464
465class NodeTypeResource:
466    def __init__(self, http: SyncHttpClient):
467        self._http = http
468
469    def list(self) -> builtins.list[NodeType]:
470        """
471        List workflow node types
472        Returns an array of all node type definitions registered with the workflow host. Node
473        types describe the available building blocks for constructing workflow graphs, including
474        each type's label, category, color, and configurable field definitions.
475        This endpoint requires a valid authenticated session. It does not support pagination
476        all registered node types are returned in a single response. The list reflects the
477        node types available at the time of the request; types are registered at startup and
478        do not change at runtime.
479
480        Returns:
481            Array of all registered workflow node type definitions.
482        """
483        return self._http.request("/api/v1/workflows/node_types", response_type=list[NodeType])
484
485    def get(self, node_type: str) -> NodeType:
486        """
487        Retrieve a workflow node type
488        Returns the full definition for a single workflow node type, identified by its
489        string identifier. The response includes the node type's label, description, category,
490        display properties, and the complete list of configurable field definitions.
491        Returns 404 if no node type with the given identifier is registered. This endpoint
492        requires a valid authenticated session.
493
494        Args:
495            node_type: Identifier of the node type to retrieve, e.g. `"http_request"` or `"conditional"`.
496
497        Returns:
498            The requested workflow node type definition.
499        """
500        return self._http.request(
501            f"/api/v1/workflows/node_types/{node_type}",
502            response_type=NodeType,
503        )
504
505
506class SampleResource:
507    def __init__(self, http: SyncHttpClient):
508        self._http = http
509
510    def list(self) -> dict[str, str]:
511        """
512        Retrieve a sample workflow graph
513        Returns a minimal, runnable `WorkflowGraph` YAML document that illustrates the
514        structure of a workflow graph. Use this as a starting point when building or
515        testing your own workflow definitions.
516        The response is returned as plain YAML (`application/x-yaml`) rather than JSON.
517        The sample graph includes a trigger node, a transform node, and an event-emit
518        node wired together in sequence.
519
520        Returns:
521            Minimal runnable WorkflowGraph YAML document.
522        """
523        return self._http.request_raw("/api/v1/workflows/sample")
524
525
526class WorkflowResource:
527    def __init__(self, http: SyncHttpClient):
528        self._http = http
529        self.events = EventResource(http)
530        self.expressions = ExpressionResource(http)
531        self.graph = GraphResource(http)
532        self.node_types = NodeTypeResource(http)
533        self.sample = SampleResource(http)
534
535    def commands(self) -> list[Command]:
536        """
537        List available workflow commands
538        Returns the full set of workflow commands registered with the workflow host.
539        Commands represent discrete operations that a workflow node can invoke each
540        carries its own input and output schemas used by the workflow builder.
541        This endpoint requires a valid developer session. The list is not paginated;
542        all registered commands are returned in a single response.
543
544        Returns:
545            Array of all registered workflow command definitions.
546        """
547        return self._http.request("/api/v1/workflows/commands", response_type=list[Command])
548
549    def llm_txt(self) -> dict[str, str]:
550        """
551        Retrieve the workflow-authoring LLM prompt
552        Returns the plain-text system prompt used by workflow-authoring assistants.
553        The prompt is rendered from the registered node types and commands so its
554        authoring guidance stays synchronized with the running platform.
555
556        Returns:
557            Plain-text system prompt for workflow-authoring assistants.
558        """
559        return self._http.request_raw("/api/v1/workflows/llm.txt")
560
561    def run(self, input: WorkflowRunInput) -> WorkflowRunResponse:
562        """
563        Execute a workflow node or graph
564        Executes a single workflow node or a complete workflow graph and returns the result.
565        Supply either `node` (to run one node in isolation) or `graph` (to execute a full
566        directed graph); the two parameters are mutually exclusive and exactly one must be
567        provided.
568        The authenticated developer is used as the default workflow principal for entitlement
569        checks on billable operations such as LLM calls. Supply `run_as_user` or
570        `run_as_agent` to override the acting identity for the execution at most one
571        override may be set per request. Overrides are subject to the caller's
572        delegation permissions, the same ones `/scripts/run` applies: app secret keys
573        and developer tokens may run as any user or agent in the app; other callers may
574        run as themselves, and as an agent they own (org admins as any agent in their
575        org). A refused override returns 403 before anything runs.
576        Execution errors are logged to the activity feed under the acting identity so they
577        appear alongside automation-driven workflow errors in operator dashboards. A 422
578        response is returned when execution fails; the response body includes the error
579        message and any partial records produced before the failure.
580
581        Args:
582            input: Request body.
583            input.context: Additional execution context made available to workflow nodes at runtime. Merged with the authenticated viewer context set by the platform. Defaults to an empty object if omitted.
584            input.env: Evaluator environment variables injected into expression contexts during execution. The platform automatically merges developer-tier runtime env vars before evaluation. Defaults to an empty object if omitted.
585            input.graph: A complete workflow graph to execute. Must be an object conforming to the `WorkflowGraph` schema (keys: `start_node`, `nodes`, etc.). Mutually exclusive with `node` supply exactly one.
586            input.node: A single workflow node to execute in isolation. Must be an object with at minimum a `type` key identifying the node kind, plus any node-specific configuration values. Mutually exclusive with `graph` supply exactly one.
587            input.payload: Arbitrary input data passed into the workflow as the initial payload. Defaults to an empty object if omitted.
588            input.run_as_agent: Agent ID (`agt_...`) of the agent to impersonate for the execution. When set, workflow nodes run with this agent as the acting principal instead of the authenticated developer. The agent must belong to the current app. Mutually exclusive with `run_as_user`. `null` by default (runs as the authenticated developer).
589            input.run_as_user: User ID (`usr_...`) of the user to impersonate for the execution. When set, workflow nodes run with this user as the acting principal instead of the authenticated developer. Mutually exclusive with `run_as_agent`. `null` by default (runs as the authenticated developer).
590
591        Returns:
592            Successful response
593        """
594        return self._http.request(
595            "/api/v1/workflows/run",
596            method="POST",
597            body=input,
598            response_type=WorkflowRunResponse,
599        )