Skip to content

Migration Guide: v0.2 → v0.3

A 5-minute checklist for upgrading from Machina v0.2.x to v0.3.0.

Breaking Changes

1. Capability type: list[str] → frozenset[Capability]

What changed: Connector capabilities are now a frozenset[Capability] (typed enum) instead of list[str].

Migration:

# v0.2 (old)
class MyConnector:
    capabilities = ["read_assets", "create_work_order"]

# v0.3 (new)
from machina.connectors.base import Capability

class MyConnector:
    capabilities = frozenset({Capability.READ_ASSETS, Capability.CREATE_WORK_ORDER})

Compatibility: The connector registry accepts both formats during v0.3.x (dual-accept). The old list[str] format will be removed in v0.4. Migrate now to avoid warnings.

2. Capability values

The full Capability enum:

# CMMS
READ_ASSETS, READ_WORK_ORDERS, GET_WORK_ORDER, CREATE_WORK_ORDER,
UPDATE_WORK_ORDER, CLOSE_WORK_ORDER, CANCEL_WORK_ORDER,
READ_SPARE_PARTS, READ_MAINTENANCE_PLANS, READ_MAINTENANCE_HISTORY

# IoT
SUBSCRIBE_TO_NODES, READ_NODE_VALUE, READ_NODE_VALUES, BROWSE_NODES,
SUBSCRIBE_TO_TOPICS, PUBLISH_MESSAGE,
GET_RELATED_READINGS, GET_LATEST_READING

# Documents
SEARCH_DOCUMENTS, RETRIEVE_SECTION

# Communication
SEND_MESSAGE, RECEIVE_MESSAGE

# Calendar
READ_CALENDAR_EVENTS, CREATE_CALENDAR_EVENT, DELETE_CALENDAR_EVENT

3. MCP server replaces the stub

The machina.mcp.MCPServer stub from v0.2.1 (which raised NotImplementedError) is replaced by a real MCP server. If your code caught that error, remove the try/except.

New Features (No Migration Needed)

These are additive — existing code continues to work:

  • MCP Server — expose connectors via Model Context Protocol (python -m machina.mcp)
  • Excel/CSV Connector — read/write maintenance data from spreadsheets
  • SQL Connector — read from PostgreSQL, SQL Server, SQLite, DB2
  • GenericCmms YAML Mapper — zero-Python entity mapping for REST APIs
  • ActionTracer v2 — cost tracking, conversation IDs, JSONL export with redaction
  • Docker deployment — docker compose up with mock CMMS
  • systemd deployment — production-ready service unit
  • Starter-kit template — odl-generator-from-text

Checklist

  • [ ] Update dependency: pip install --upgrade "machina-ai[mcp]>=0.3.0"
  • [ ] If you have custom connectors: migrate capabilities from list[str] to frozenset[Capability]
  • [ ] If you caught MCPServer NotImplementedError: remove the try/except
  • [ ] Run your tests — pytest should catch any remaining issues
  • [ ] (Optional) Try the MCP server: python -m machina.mcp --config machina.yaml

Timeline

Version Capability format
v0.2.x list[str] only
v0.3.x Both accepted (dual-accept registry)
v0.4.0 frozenset[Capability] only — list[str] removed