Metadata-Version: 2.4
Name: mtrxai-workflow-sdk
Version: 0.4.0
Summary: Lightweight workflow SDK and mtrxai CLI for mtrxai workflow developers.
License-Expression: Apache-2.0
Keywords: agent,mtrxai,langgraph,sdk,workflow
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=1.2.8
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: llm
Requires-Dist: langchain-openai>=1.1.10; extra == "llm"
Provides-Extra: langchain-mcp
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == "langchain-mcp"
Dynamic: license-file

# mtrxai-workflow-sdk

`mtrxai-workflow-sdk` 0.4.0 is the Python SDK and authoring CLI for local mtrxai
workflows. Workflows run only in the local desktop Runtime. It includes the native capability
contract, durable steps/events, resource APIs, native HITL surfaces, checkpoint support, local MCP
authorization, fixture tools and deterministic `.mtrxw` packaging.

Install the published SDK from PyPI:

```bash
python -m pip install mtrxai-workflow-sdk==0.4.0
mtrxai workflow create --name tag_extractor \
  --description "Extract reviewable tags from the user's uploaded source files."
mtrxai workflow run --workflow ./workflows/tag_extractor \
  --fixture ./workflows/tag_extractor/tests/fixtures/sample_workspace.json
```

For an unpublished or locally verified release, install the wheel produced by
`scripts/build-workflow-sdk.sh` instead:

```bash
python -m pip install ./sdk/dist/mtrxai_workflow_sdk-0.4.0-py3-none-any.whl
```

Generate the complete LangGraph patterns sample as an independent Agent repository without copying
files from the framework source tree:

```bash
mtrxai agent create --sample --target ./agents
cd ./agents/langgraph-patterns-agent
pnpm install --frozen-lockfile
pnpm build
```

The sample name and module IDs are fixed, so `--sample` cannot be combined with `--name`.

The generated project is immediately fixture-runnable and includes `uv.lock`, which is required for
desktop installation. Register a source tree during development, or package a reproducible release:

```bash
mtrxai workflow dev --source ./workflows/tag_extractor
cd ./workflows/tag_extractor
uv lock
mtrxai workflow package --workflow . --out dist/tag_extractor.mtrxw
mtrxai workflow verify-package --package dist/tag_extractor.mtrxw
mtrxai workflow install --package dist/tag_extractor.mtrxw
```

Each generated Workflow also includes `skills/mtrxai-workflow-<name>/SKILL.md`. Hermes reads its
frontmatter to discover when the main Agent should call the Workflow. Treat `--description` as the
user-intent trigger: make it specific to the business task, inputs and expected outcome rather than
using a generic implementation description.

Create a fixture directly from local files; no upload or server workspace is involved:

```bash
mtrxai resource fixture create --workspace-id 2001 --file ./samples/report.txt \
  --type-key document --folder upload --out ./sample_workspace.json
```

For fast desktop Runtime debugging, run `mtrxai workflow dev --source <workflow-dir>`.
Package a local release with `mtrxai workflow package`, then install it using
`mtrxai workflow install`. The package includes no container or remote workflow deployment path.

For model calls, import `get_chat_model` from `packages.workflow_sdk`. The local Runtime injects a
per-run desktop LLM Proxy session; workflow source and `.env` files must not contain provider API
keys or a direct model base URL. Add the optional LLM dependency to the Workflow project before
using a model node:

```bash
uv add "langchain-openai>=1.1.10"
uv lock
```

Use `get_chat_model(ctx, node_id="stable-node-id")`, passing the current `WorkflowContext`. The
source repository's `docs/development/workflow-sdk-development.md` contains the complete manifest,
capability, resource, HITL, MCP, checkpoint, package and troubleshooting guidance.
