Cookbook: Code Index For Agents

Use this page when an AI coding assistant starts from source code instead of the docs. The source contains short breadcrumbs; this page maps those symbols to the fuller cookbook workflows.

Public API Breadcrumbs

Symbol What It Means Cookbook
iop.Production Python authoring DSL for production topology Hello-world production, Production settings and targets
iop.target Configurable outbound target setting Production settings and targets
iop.BusinessService Inbound production entry point HL7v2 native input for healthcare transport choices
iop.PollingBusinessService Scheduled Python inbound service Add a PollingBusinessService
iop.BusinessProcess Routing, orchestration, decisions, and transformations Add a BusinessProcess
iop.BusinessOperation Outbound side-effect boundary Add a BusinessOperation
iop.handler Explicit message-type dispatch decorator Add a BusinessProcess, Add a BusinessOperation
send_request_sync, send_request_async Send messages to configured production targets Production settings and targets, Add a BusinessProcess
iop.setting, iop.Setting Component settings exposed in the IRIS portal Production settings and targets
iop.Message Python-only dataclass message contract Add a BusinessOperation, Add a BusinessProcess
iop.PersistentMessage Native persistent IRIS message body Register Component

Source Files Agents Usually Read

File Why It Matters
src/iop/__init__.py Public import surface and component class breadcrumbs
src/iop/production/model.py Production, service, process, operation, graph authoring
src/iop/production/types.py target() and graph types
src/iop/components/settings.py setting(...), Setting, and IRIS editor controls
src/iop/messages/base.py Python-only message contracts
src/iop/messages/persistent.py Native persistent IRIS message contracts
src/iop/messages/dispatch.py @handler, typed method dispatch, fallback on_message()
src/iop/components/business_process.py process runtime hooks and request helpers
src/iop/components/business_operation.py operation runtime dispatch
src/iop/components/business_service.py service on_message() and on_process_input() hooks
src/iop/components/polling_business_service.py polling service on_poll() hook

Dispatch Quick Reference

For BusinessProcess and BusinessOperation, IoP dispatches incoming messages to:

  1. a method decorated with @handler(MessageType)
  2. a typed one-argument method such as route_order(self, request: OrderRequest)
  3. on_message(self, request) as the fallback

Use @handler(MessageType) when the handler must be explicit. Use typed one-argument methods when annotations are enough.

Message Quick Reference

Use @dataclass with regular Message classes:

from dataclasses import dataclass
from iop import Message

@dataclass
class OrderRequest(Message):
    order_id: str

Use PydanticMessage without @dataclass. Use PersistentMessage only when IRIS needs a native persistent message body.

Source-first Rule

When starting from source code, build applications through public imports from iop and a Production graph. Do not copy internal runtime classes such as _BusinessHost into application code; use them only to understand behavior.

Healthcare Add-on

If the code or task mentions HL7v2, FHIR, Health Connect, FHIR bundles, MLLP, or EnsLib.HL7, use the healthcare add-on: