mistralai-workflows-cli 1.2.2__tar.gz → 1.2.3__tar.gz

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.2.3}/Makefile

@@ -42,6 +42,7 @@ integration-test:
 	$(MAKE) _test-start-examples
 	$(MAKE) _test-execute-help
 	$(MAKE) _test-execute-bad-json
+	$(MAKE) _test-make-check
 	$(MAKE) _test-wheel-contents
 	@echo ""
 	@echo "All integration tests passed."
@@ -124,3 +125,8 @@ _test-wheel-contents:
 		| grep -q "entrypoints/worker.py" \
 		&& echo "OK: wheel contains entrypoints package" \
 		|| (echo "FAIL: wheel is missing the entrypoints package" && exit 1)
+
+_test-make-check:
+	@echo "--- test: 'make check' (ruff, mypy, workflow lint) passes on the generated project"
+	cd $(GENERATED_PROJECT) && $(MAKE) check
+	@echo "OK: make check passes on the generated project"

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mistralai-workflows-cli
-Version: 1.2.2
+Version: 1.2.3
 Summary: CLI to bootstrap Mistral Workflows projects
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.2.3}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/SKILL.md

@@ -76,8 +76,8 @@ The documentation is organized into several categories:
 - **[Connectors](references/guides/connectors.mdx)**: Call third-party tools (GitHub, Notion, Slack, ...) from a workflow or give them to an agent, without holding the service's credentials
 - **[Conversational Workflows](references/guides/assist-workflows.mdx)**: InteractiveWorkflow, HITL, ChatInput/FormInput, Canvas editing, Rich UI components, Tool UI states
 - **[Local Execution](references/guides/local-execution.mdx)**: No-infra dev mode with Pydantic model params
-- **[Limitations](references/guides/limitations.mdx)**: System constraints and limits
-- **[Workflows Plugins](references/guides/workflows-plugins.mdx)**: Mistral AI plugin, Webhook plugin, Nuage plugin, custom plugins
+- **[Limitations](references/guides/limitations.mdx)**: System constraints, determinism rules, sandbox import restrictions (module-level non-deterministic imports + `imports_passed_through`), I/O and heavy work belongs in activities, execution-history limits
+- **[Workflows Plugins](references/guides/workflows-plugins.mdx)**: Mistral AI plugin (calling chat / structured-output / embeddings / OCR models), Webhook plugin, Nuage plugin, custom plugins
 - **[Deployment Patterns](references/guides/_deployment-patterns.mdx)**: Best practices for deploying workflows
 - **[Migration v2 to v3](references/guides/migration-v2-to-v3.mdx)**: Breaking changes and upgrade steps from SDK v2 through v3.4.0
 
@@ -101,6 +101,16 @@ python .agents/skills/workflows/scripts/test_workflow.py <workflow_file> --input
 
 If a workflow is known to be long-running (e.g. multi-step agent, large data processing), increase timeouts proportionally — but start short and only raise them when you see legitimate timeout failures, not preemptively.
 
+**Lint & check** — validate your code before running it. Three checks are available:
+- `make lint` — Ruff: style, imports, and common errors (`make format` auto-fixes most)
+- `make typecheck` — mypy static type checking
+- `make lint-workflows` — Semgrep workflow rules: determinism violations, I/O outside activities, missing return-type annotations, unsafe imports (advisory — reports but does not block)
+
+Run all three at once after writing or editing a workflow, and address any findings:
+```bash
+make check
+```
+
 ### Internal References
 
 These are additional patterns and utilities not covered in the official docs:
@@ -139,4 +149,3 @@ Use this skill when you need to:
 - **Durable agents**: AI agents with MCP support, multi-agent handoffs, and persistent state
 - **Connectors**: Call external services with platform-managed credentials avoiding secrets in the workflow code
 - **Scalability**: Designed to handle complex, distributed applications
-

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.2.3}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/limitations.mdx

@@ -144,6 +144,17 @@ if os.getenv("ENV") == "prod":
 
 must be performed in activities. While activities themselves can produce different outputs for the same inputs (as they might contain non-deterministic operations), the workflow code must behave deterministically based on the activity results it receives.
 
+### Imports must be deterministic too
+
+The sandbox also validates **imports**. A module-level `import` of a non-deterministic library (`httpx`, `requests`, `aiohttp`, the raw `mistralai` client, etc.) in a workflow file won't work in the sandbox — the worker rejects it while validating the workflow at startup, so the workflow never becomes runnable. Keep such imports **inside the activity** that uses them, or — when a top-level import is unavoidable (e.g. shared type hints) — wrap it so the sandbox lets it through:
+
+```python
+with workflows.workflow.unsafe.imports_passed_through():
+    import httpx
+```
+
+Only pass through imports you know are side-effect-free (no import-time I/O or global-state mutation).
+
 ### Maximum Execution History
 
 The execution history for each workflow is capped at 51,200 events or 50MB per workflow execution. This is a hard limit of the durable execution engine. In order to avoid hitting this limit, we recommend using `workflows.execute_activities_in_parallel`, that allows you to execute large amounts of activities in parallel, while having the lowest footprint on the execution history. [Learn more about concurrency patterns](concurrency).

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.2.3}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/rate-limiting.mdx

@@ -28,7 +28,8 @@ When **a key is provided**, multiple different activities that use the same key
 
 ```python
 import mistralai.workflows as workflows
-from mistralai import Mistral, Messages
+from mistralai.client import Mistral
+from mistralai.client.models import ChatCompletionRequestMessage
 from mistralai.workflows import Depends
 from pydantic import BaseModel
 
@@ -41,7 +42,7 @@ def get_mistral_client() -> Mistral:
 
 class CompletionParams(BaseModel):
     model: str
-    messages: Messages
+    messages: list[ChatCompletionRequestMessage]
 
 @workflows.activity(rate_limit=workflows.RateLimit(time_window_in_sec=1, max_calls=100))
 async def generate_chat_response(

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.2.3}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/workflows-plugins.mdx

@@ -78,6 +78,72 @@ class SummarizeWorkflow:
         return result.choices[0].message.content
 ```
 
+**Example — structured output:** to get a validated Pydantic object back instead of a string, define a model and build the same `ChatCompletionRequest` as above, then swap the final call for `chat_parse_to_model`:
+
+```python
+from pydantic import BaseModel
+from mistralai.workflows.plugins.mistralai import chat_parse_to_model
+
+class Sentiment(BaseModel):
+    label: str
+    score: float
+
+# inside the entrypoint, with `request` built as in the chat example above:
+sentiment = await chat_parse_to_model(Sentiment, request)
+```
+
+For the raw response instead of a parsed model, call `mistralai_chat_parse(request, response_format)` directly.
+
+**Example — embeddings** (call from inside an entrypoint or activity):
+
+```python
+from mistralai.workflows.plugins.mistralai import (
+    MistralEmbeddingsParams,
+    mistralai_embeddings,
+)
+
+response = await mistralai_embeddings(
+    MistralEmbeddingsParams(model="mistral-embed", inputs=["first text", "second text"]),
+)
+vectors = [item.embedding for item in response.data]
+```
+
+**Example — OCR** extracts text from a document or image URL:
+
+```python
+from mistralai.client.models import DocumentURLChunk
+from mistralai.workflows.plugins.mistralai import OCRRequest, mistralai_ocr
+
+result = await mistralai_ocr(
+    OCRRequest(
+        model="mistral-ocr-latest",
+        document=DocumentURLChunk(document_url="https://example.com/invoice.pdf"),
+    ),
+)
+pages_markdown = [page.markdown for page in result.pages]
+```
+
+**Raw client (when a plugin activity isn't enough):** call the Mistral API directly from inside an activity. Import the client from `mistralai.client` — `mistralai` is a namespace package, so `from mistralai import Mistral` does **not** work — and keep that import inside the activity function so the workflow sandbox doesn't reject it:
+
+```python
+import os
+from mistralai.workflows import activity
+
+@activity()
+async def summarize(text: str) -> str:
+    # Import inside the activity so the workflow sandbox doesn't reject it.
+    from mistralai.client import Mistral  # NOT `from mistralai import Mistral`
+
+    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
+    resp = await client.chat.complete_async(
+        model="mistral-small-latest",
+        messages=[{"role": "user", "content": text}],
+    )
+    return resp.choices[0].message.content
+```
+
+Model calls and other I/O must run inside an activity, never in the workflow body; see [Limitations](./limitations) for the determinism and import rules.
+
 For full documentation on `Agent`, `Runner`, sessions, MCP, and multi-agent handoffs, see the [Durable Agents guide](./durable-agents).
 
 ### Webhook Plugin

mistralai_workflows_cli-1.2.3/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/scripts/linting/rules/determinism.yaml

@@ -0,0 +1,217 @@
+rules:
+  # Workflow code runs inside a determinism sandbox and is replayed on
+  # recovery.  Non-deterministic operations break replay.  These rules
+  # flag non-deterministic stdlib calls inside `@workflow.define` classes
+  # (the workflow classes).  Activities and plain helper classes are exempt.
+
+  - id: no-datetime-now-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: datetime.now(...)
+          - pattern: datetime.datetime.now(...)
+          - pattern: datetime.utcnow(...)
+          - pattern: datetime.datetime.utcnow(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Use `workflow.now()` instead of `datetime.now()` in workflow code.
+      Workflows must be deterministic — `datetime.now()` returns
+      different values on replay, breaking the execution history.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Replace with `workflow.now()` from `mistralai.workflows`
+
+  - id: no-uuid4-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: uuid.uuid4(...)
+          - pattern: uuid4(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Use `workflow.uuid4()` instead of `uuid.uuid4()` in workflow code.
+      Standard UUID generation is non-deterministic and breaks replay.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Replace with `workflow.uuid4()` from `mistralai.workflows`
+
+  - id: no-random-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: random.random(...)
+          - pattern: random.randint(...)
+          - pattern: random.choice(...)
+          - pattern: random.shuffle(...)
+          - pattern: random.sample(...)
+          - pattern: random.uniform(...)
+          - pattern: random.randrange(...)
+          - pattern: random.gauss(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Use `workflow.random()` instead of the `random` module in workflow
+      code. Standard random functions are non-deterministic and break
+      replay.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Replace with `workflow.random()` from `mistralai.workflows`
+
+  - id: no-os-env-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: os.environ
+          - pattern: os.environ[...]
+          - pattern: os.environ.get(...)
+          - pattern: os.getenv(...)
+          - pattern: os.getcwd(...)
+          - pattern: os.listdir(...)
+          - pattern: os.path.exists(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Do not access `os.environ`, `os.getenv()`, `os.getcwd()`, or
+      filesystem functions in workflow code. Environment variables and
+      filesystem state can differ between replays. Read config in an
+      activity and pass it as workflow input, or use dependency injection.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Move to an activity or use dependency injection (Depends)
+
+  - id: no-time-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: time.time(...)
+          - pattern: time.monotonic(...)
+          - pattern: time.sleep(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Do not use `time.time()`, `time.monotonic()`, or `time.sleep()`
+      in workflow code. Use `workflow.now()` for timestamps and
+      `asyncio.sleep()` for delays (which is durable and survives
+      replays).
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Use `workflow.now()` for time, `asyncio.sleep()` for delays
+
+  - id: no-hashlib-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: hashlib.sha256(...)
+          - pattern: hashlib.sha512(...)
+          - pattern: hashlib.md5(...)
+          - pattern: hashlib.sha1(...)
+          - pattern: hashlib.new(...)
+          - pattern: hashlib.pbkdf2_hmac(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Cryptographic operations are CPU-intensive and can exceed the
+      2-second limit between activities. Move hashing to an activity:
+        @activity()
+        async def hash_data(data: bytes) -> str:
+            return hashlib.sha256(data).hexdigest()
+    severity: WARNING
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Move cryptographic operations to an activity
+
+  - id: no-global-in-workflow
+    patterns:
+      - pattern: global $VAR
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Do not use `global` in workflow code. Modifying global variables
+      is non-deterministic — the global state may differ between
+      replays. Store state on `self` or pass it through activities.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Use `self.field` for workflow state, or pass data via activities
+
+  - id: no-model-validate-in-workflow
+    patterns:
+      - pattern: $MODEL.model_validate(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Pydantic `.model_validate()` can be CPU-intensive on large
+      payloads and may exceed the 2-second limit between activities.
+      Move heavy validation to an activity:
+        @activity()
+        async def validate(data: dict) -> MyModel:
+            return MyModel.model_validate(data)
+    severity: WARNING
+    languages: [python]
+    metadata:
+      category: determinism
+      fix: Move validation to an activity

mistralai_workflows_cli-1.2.3/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/scripts/linting/rules/imports.yaml

@@ -0,0 +1,114 @@
+rules:
+  - id: no-temporalio-import
+    pattern-either:
+      - pattern: import temporalio
+      - pattern: import temporalio.$MOD
+      - pattern: from temporalio import $X
+      - pattern: from temporalio.$MOD import $X
+    message: >-
+      Do not import `temporalio` directly. The workflows SDK re-exports
+      everything you need: `workflow.now()`, `workflow.uuid4()`,
+      `workflow.random()`, `workflow.wait_condition()`,
+      `workflow.continue_as_new()`, `WorkflowError`, `ActivityError`,
+      `ParentClosePolicy`, etc.
+      Use `from mistralai.workflows import ...` instead.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: import
+      fix: Replace with the equivalent import from `mistralai.workflows`
+
+  - id: top-level-httpx-import
+    patterns:
+      - pattern: import httpx
+      - pattern-not-inside: |
+          def $F(...):
+              ...
+      - pattern-not-inside: |
+          async def $F(...):
+              ...
+    message: >-
+      Avoid top-level `import httpx`. The determinism sandbox re-imports
+      modules, and top-level imports with side effects can cause issues.
+      Import httpx inside your activity function instead:
+        @activity()
+        async def call_api(url: str) -> dict:
+            import httpx
+            async with httpx.AsyncClient() as client: ...
+    severity: WARNING
+    languages: [python]
+    metadata:
+      category: import
+      fix: Move `import httpx` inside the activity function body
+
+  - id: top-level-requests-import
+    patterns:
+      - pattern-either:
+          - pattern: import requests
+          - pattern: from requests import $X
+      - pattern-not-inside: |
+          def $F(...):
+              ...
+      - pattern-not-inside: |
+          async def $F(...):
+              ...
+    message: >-
+      Do not use the `requests` library. It is synchronous and blocks
+      the event loop. Use `httpx.AsyncClient` instead, imported inside
+      your activity function.
+    severity: WARNING
+    languages: [python]
+    metadata:
+      category: import
+      fix: Remove `requests` and use `httpx.AsyncClient` in activities
+
+  - id: top-level-aiohttp-import
+    patterns:
+      - pattern-either:
+          - pattern: import aiohttp
+          - pattern: from aiohttp import $X
+      - pattern-not-inside: |
+          def $F(...):
+              ...
+      - pattern-not-inside: |
+          async def $F(...):
+              ...
+    message: >-
+      Avoid top-level `import aiohttp`. Import it inside your activity
+      function to avoid sandbox re-import issues.
+    severity: WARNING
+    languages: [python]
+    metadata:
+      category: import
+      fix: Move the import inside the activity function body
+
+  - id: top-level-mistral-client-import
+    patterns:
+      - pattern-either:
+          - pattern: import mistralai.client
+          - pattern: import mistralai.client.$SUB
+          - pattern: from mistralai.client import $X
+          - pattern: from mistralai.client.$SUB import $X
+      - pattern-not-inside: |
+          def $F(...):
+              ...
+      - pattern-not-inside: |
+          async def $F(...):
+              ...
+      - pattern-not-inside: |
+          with workflows.workflow.unsafe.imports_passed_through():
+              ...
+      - pattern-not-inside: |
+          with workflow.unsafe.imports_passed_through():
+              ...
+    message: >-
+      Avoid a top-level import from `mistralai.client` (the raw SDK). It pulls in
+      `httpx`, which the determinism sandbox rejects when it re-imports the workflow
+      module — the worker then fails to validate the workflow at startup. Prefer the
+      Mistral AI plugin activities (`mistralai_chat_complete`, `mistralai_ocr`, ...);
+      if you genuinely need the raw client, import it inside the activity that uses it.
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: import
+      fix: Use a plugin activity, or import `mistralai.client` inside the activity body

mistralai_workflows_cli-1.2.3/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/scripts/linting/rules/io.yaml

@@ -0,0 +1,116 @@
+rules:
+  # All I/O must be performed in activities.  Workflow code may be
+  # replayed, and I/O operations would violate determinism or cause
+  # duplicate side effects.
+
+  - id: no-file-io-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: open(...)
+          - pattern: aiofiles.open(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Do not perform file I/O in workflow code. Move file operations
+      to an activity:
+        @activity()
+        async def read_file(path: str) -> str:
+            async with aiofiles.open(path) as f:
+                return await f.read()
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: io
+      fix: Move file I/O to an activity function
+
+  - id: no-http-client-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: httpx.AsyncClient(...)
+          - pattern: httpx.Client(...)
+          - pattern: aiohttp.ClientSession(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Do not make HTTP calls in workflow code. Move all HTTP/API calls
+      to an activity:
+        @activity()
+        async def call_api(url: str) -> dict:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(url)
+                return resp.json()
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: io
+      fix: Move HTTP calls to an activity function
+
+  - id: no-db-in-workflow
+    patterns:
+      - pattern-either:
+          - pattern: await $CONN.execute(...)
+          - pattern: await $CONN.fetch(...)
+          - pattern: await $CONN.fetchone(...)
+          - pattern: await $CONN.fetchall(...)
+          - pattern: await $CONN.fetchrow(...)
+          - pattern: await $CONN.query(...)
+          - pattern: await $CONN.commit(...)
+          - pattern: $CONN.commit(...)
+      - pattern-either:
+          - pattern-inside: |
+              @workflow.define(...)
+              class $CLASS:
+                  ...
+          - pattern-inside: |
+              @workflows.workflow.define(...)
+              class $CLASS:
+                  ...
+    message: >-
+      Do not perform database operations in workflow code. Move all
+      database queries to an activity. Use dependency injection
+      (Depends) to provide the connection:
+        @activity()
+        async def query_db(
+            q: str,
+            conn: Connection = Depends(get_connection),
+        ) -> list[dict]:
+            return await conn.fetch(q)
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: io
+      fix: Move database operations to an activity function
+
+  - id: no-sync-requests-library
+    pattern-either:
+      - pattern: requests.get(...)
+      - pattern: requests.post(...)
+      - pattern: requests.put(...)
+      - pattern: requests.delete(...)
+      - pattern: requests.patch(...)
+      - pattern: requests.head(...)
+      - pattern: requests.request(...)
+    message: >-
+      The `requests` library is synchronous and blocks the event loop.
+      Use `httpx.AsyncClient` instead:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+    severity: ERROR
+    languages: [python]
+    metadata:
+      category: async
+      fix: Replace `requests` with `httpx.AsyncClient`