# Mistral Workflows SDK — Development Guidelines

## Project Context

`workflow_sdk` is the Python SDK for defining and running Mistral Workflows. It provides the decorator-based API and the client for submitting and querying workflow executions.

## Code Style Guidelines

### Formatting
- Do not put import statements inside functions or classes unless strictly required to avoid circular imports.

### Comments and Documentation

**Add docstrings only when:**
- The function is part of the public API (exported from the SDK surface).
- The logic is genuinely complex and not self-explanatory.

**Do not add comments that:**
- Restate what the code obviously does.
- Announce what was just added or changed.

### General Guidelines

- Write self-documenting code with clear variable and function names.
- Follow existing patterns in the codebase.
- Keep the public API surface minimal — internal helpers should not leak.

## Testing

The SDK has two test layers:

| Layer | When to use |
|-------|-------------|
| Unit (`make test`) | Default — tests SDK behavior in-process without Docker |
| Integration (`make integration-tests`) | Only for SDK↔API contract (registration, execution, auth) |

Unit tests use Temporal's `WorkflowEnvironment` (in-process) via the `temporal_env` fixture in `conftest.py`. No Docker required.

**Rules:**
- Mock only external side effects inside activities (HTTP, filesystem, third-party clients). Never mock Temporal.
- Test observable behavior, not implementation details.
- Never mix SDK concerns and API concerns in a single test.
- Tests must be runnable anywhere: dev machines, CI, staging, on-prem.
- Group related tests with classes and methods.
- Use `pytest.mark.parametrize` to share test logic across multiple inputs.

## Tooling and Setup

- Use `uv` for dependency management and running tools.

### Standard Makefile Targets

- `make lint`: Run linting, formatting validation, and type checks.
- `make format`: Auto-format code.
- `make typecheck`: Run static type checking only.
- `make test`: Run the unit test suite.
- `make integration-tests`: Run integration tests against the local stack.
- `make installdeps`: Install dependencies and update lock files.
- `make check-api-surface`: Detect breaking changes to the public API surface.

For more granular control, use `uv run invoke` directly. For example, to run a specific test:

```
uv run invoke tests -k test_specific_name
```

### Changelog

Every PR that touches `workflow_sdk` must include a changelog fragment or it will fail CI. Use `ovide` to create one:

```
uv run ovide new
```

This creates a file in `changelog.d/` with a bump level (`patch`, `minor`, `major`) and a kind (`Added`, `Changed`, `Fixed`, etc.). If the change genuinely does not warrant a changelog entry (e.g. CI or tooling fixes), add the `no-changelog` label to the PR instead.
