iris-pex-embedded-python 4.1.0b1__py3-none-any.whl → 4.1.1b2__py3-none-any.whl

iop/ai/__init__.py

@@ -0,0 +1,9 @@
+"""Packaged AI guidance and project installer for IoP applications."""
+
+from .installer import AgentGuidanceConflictError, InstallResult, install_agent_guidance
+
+__all__ = [
+    "AgentGuidanceConflictError",
+    "InstallResult",
+    "install_agent_guidance",
+]

iop/ai/guidance/instructions.md

@@ -0,0 +1,72 @@
+# IoP Application Guidance
+
+This repository contains an IoP application. IoP means Interoperability On
+Python: a Python-first framework for building InterSystems IRIS and Health
+Connect interoperability productions.
+
+## Start With The Application
+
+Before a major change, establish the business goal, inbound and outbound
+systems, protocols or standards, routing and transformation behavior, runtime
+constraints, and acceptance criteria. Infer facts from the repository before
+asking the user.
+
+Read the project README, `settings.py`, the production graph, message and
+component modules, tests, fixtures, sample payloads, dependency files, and
+available Docker or Compose lifecycle. Use the bundled `build-iop-app` skill
+for implementation workflows and `validate-iop-app` for verification.
+
+## IoP Rules
+
+- Prefer a Python `Production` exported through `PRODUCTIONS`.
+- Declare topology with `prod.service(...)`, `prod.process(...)`,
+  `prod.operation(...)`, and graph connections.
+- Declare configurable outbound routes with `target()` and connect them through
+  the production graph.
+- Communicate between production components through messages and configured
+  targets. Do not instantiate another production component directly.
+- Use `on_init()` for startup and `on_tear_down()` for cleanup. Do not put
+  component startup logic in `__init__()`.
+- Use `@dataclass` on regular `Message` classes. Do not add `@dataclass` to
+  `PydanticMessage` classes.
+- Use `PersistentMessage` only when IRIS requires a native persistent message
+  body.
+- Prefer typed one-argument handlers or `@handler(MessageType)`. Use
+  `on_message(self, request)` as a simple fallback.
+- Avoid raw `CLASSES` entries for components already declared in a production
+  graph. Keep them for standalone bindings and legacy migrations.
+- Keep executable migration examples behind `if __name__ == "__main__":` so
+  `PRODUCTIONS` can be imported safely.
+
+## Project Imports
+
+Treat the directory containing `settings.py` as the project import root. Use
+modules reachable relative to that file. Fix package layout or imports instead
+of modifying `PYTHONPATH`, `os.environ["PYTHONPATH"]`, or global `sys.path` in
+application code.
+
+## Production Design
+
+- Business Services are inbound entry points and triggers. A polling service
+  owns acquisition from the source it polls, including an HTTP, file, or
+  database read, and emits a data-bearing message.
+- Business Processes own routing, decisions, transformations, and orchestration.
+- Business Operations isolate destination side effects such as persistence,
+  file writes, submissions, and API calls made after processing. An API lookup
+  requested by a process is also an operation; acquisition by a polling service
+  from its configured source remains service work.
+- Model a complete source-to-destination ingestion flow as `service -> process
+  -> operation` by default. Omit the process only for a genuinely trivial
+  pass-through and state why no orchestration boundary is needed.
+- Prefer native IRIS or Health Connect components for established healthcare
+  standards and transports, then use Python for application-specific logic.
+
+For an existing or shared IRIS production, inspect and plan changes before
+mutation. Use the conservative plan, review, apply, verify, and backup workflow;
+do not treat an imported graph as a lossless reconstruction of deployed intent.
+
+## Completion
+
+Add or update focused tests, declare direct dependencies, and preserve working
+project lifecycle automation when behavior changes. Run the `validate-iop-app`
+skill and report commands, results, and remaining runtime verification clearly.

iop/ai/guidance/testing.md

@@ -0,0 +1,48 @@
+# Testing IoP Applications
+
+Run the fastest relevant checks first from the project root.
+
+## Local Checks
+
+1. Run the project's Python tests:
+
+   ```bash
+   python -m pytest
+   ```
+
+2. Validate the migration without writing to IRIS:
+
+   ```bash
+   iop --migrate settings.py --dry-run --strict-production-validation
+   ```
+
+Resolve import errors through package layout and imports, not `PYTHONPATH`
+changes in application code.
+
+## Runtime Checks
+
+Use a repository-owned disposable Docker or Compose environment for runtime
+verification when it is available. Only mutate a shared, remote, or otherwise
+non-disposable IRIS environment when the user requests it and the target is
+known. Verify at least one observable result:
+
+- production and component status;
+- expected output file, API request, database write, or FHIR resource;
+- production logs without blocking errors;
+- Message Viewer flow or queue state.
+
+Container health is not production health. Confirm initialization and migration
+completed, use `iop --status` to verify the intended production is running, then
+trigger or wait for a Business Service and inspect an actual destination effect.
+Prefer `iop` commands for migration, start, status, logs, and queues. Do not use
+an ObjectScript terminal when the IoP CLI supports the operation. Automated
+checks must return control: use `iop --start <production-name> --detach` and a
+finite log snapshot such as `iop --log 50`. Bare `--start` and bare `--log`
+stream logs until interrupted.
+
+Do not use `iop --test` as the normal way to test a Business Service. Use the
+production runtime or director path so deployed settings, targets, and runtime
+context are active.
+
+For shared or brownfield productions, use a reviewed production change plan and
+backup rather than full registration by default.

iop/ai/installer.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+AGENTS = ("codex", "claude", "gemini")
+MANAGED_START = "<!-- iop-agent-guidance:start -->"
+MANAGED_END = "<!-- iop-agent-guidance:end -->"
+
+_AGENT_PATHS = {
+    "codex": ("AGENTS.md", ".codex/skills"),
+    "claude": ("CLAUDE.md", ".claude/skills"),
+    "gemini": ("GEMINI.md", ".gemini/skills"),
+}
+
+_SKILL_DESCRIPTIONS = {
+    "build-iop-app": (
+        "Build or modify an IoP application using production graphs, messages, "
+        "components, tests, and all applicable bundled cookbooks. Use for new or "
+        "changed Business Services, Business Processes, Business Operations, "
+        "routes, settings, healthcare flows, or complete productions."
+    ),
+    "validate-iop-app": (
+        "Validate an IoP application with unit tests, strict migration dry-run, "
+        "and container-backed IRIS runtime checks when available. Use after changing "
+        "messages, components, production topology, settings, migration files, "
+        "container lifecycle, or runtime behavior."
+    ),
+}
+
+
+class AgentGuidanceConflictError(ValueError):
+    """Raised when installed framework-owned guidance would be overwritten."""
+
+    def __init__(self, paths: Iterable[Path]):
+        self.paths = tuple(paths)
+        joined = ", ".join(str(path) for path in self.paths)
+        super().__init__(
+            "agent guidance conflicts with existing files: "
+            f"{joined}. Re-run with --force-agent-guidance to replace them."
+        )
+
+
+@dataclass(frozen=True)
+class InstallResult:
+    target: Path
+    agents: tuple[str, ...]
+    written: tuple[Path, ...]
+    unchanged: tuple[Path, ...]
+
+
+def install_agent_guidance(
+    target: str | Path = ".",
+    *,
+    agents: Iterable[str] | None = None,
+    force: bool = False,
+) -> InstallResult:
+    """Install version-matched IoP guidance into an application repository."""
+    target_path = Path(target).expanduser().resolve()
+    selected_agents = _normalize_agents(agents)
+    owned_files = _owned_file_manifest(target_path, selected_agents)
+    root_files = _root_file_manifest(target_path, selected_agents)
+
+    conflicts = [
+        path
+        for path, content in owned_files.items()
+        if path.exists() and path.read_bytes() != content
+    ]
+    if conflicts and not force:
+        raise AgentGuidanceConflictError(conflicts)
+
+    manifest = {**owned_files, **root_files}
+    written: list[Path] = []
+    unchanged: list[Path] = []
+    for path, content in manifest.items():
+        if path.exists() and path.read_bytes() == content:
+            unchanged.append(path)
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+        written.append(path)
+
+    return InstallResult(
+        target=target_path,
+        agents=selected_agents,
+        written=tuple(written),
+        unchanged=tuple(unchanged),
+    )
+
+
+def _normalize_agents(agents: Iterable[str] | None) -> tuple[str, ...]:
+    values = tuple(agents or AGENTS)
+    invalid = sorted(set(values) - set(AGENTS))
+    if invalid:
+        raise ValueError(f"unsupported agents: {', '.join(invalid)}")
+    return tuple(agent for agent in AGENTS if agent in values)
+
+
+def _owned_file_manifest(
+    target: Path,
+    agents: tuple[str, ...],
+) -> dict[Path, bytes]:
+    manifest: dict[Path, bytes] = {}
+    resource_root = files("iop.ai")
+    for resource_dir, destination in (
+        (resource_root.joinpath("guidance"), target / ".config" / "AGENTS"),
+        (
+            resource_root.joinpath("skills"),
+            target / ".config" / "AGENTS" / "skills",
+        ),
+    ):
+        _add_resource_tree(manifest, resource_dir, destination)
+
+    for agent in agents:
+        _, skills_root = _AGENT_PATHS[agent]
+        for skill_name, description in _SKILL_DESCRIPTIONS.items():
+            wrapper = _skill_wrapper(skill_name, description)
+            path = target / skills_root / skill_name / "SKILL.md"
+            manifest[path] = wrapper.encode("utf-8")
+    return manifest
+
+
+def _root_file_manifest(
+    target: Path,
+    agents: tuple[str, ...],
+) -> dict[Path, bytes]:
+    manifest: dict[Path, bytes] = {}
+    for agent in agents:
+        root_name, _ = _AGENT_PATHS[agent]
+        path = target / root_name
+        current = path.read_text(encoding="utf-8") if path.exists() else ""
+        merged = _merge_managed_block(current, _root_block(agent))
+        manifest[path] = merged.encode("utf-8")
+    return manifest
+
+
+def _add_resource_tree(manifest, resource, destination: Path) -> None:
+    for child in resource.iterdir():
+        child_destination = destination / child.name
+        if child.is_dir():
+            _add_resource_tree(manifest, child, child_destination)
+        elif child.name != "__pycache__":
+            manifest[child_destination] = child.read_bytes()
+
+
+def _merge_managed_block(content: str, block: str) -> str:
+    managed = f"{MANAGED_START}\n{block.rstrip()}\n{MANAGED_END}"
+    start = content.find(MANAGED_START)
+    end = content.find(MANAGED_END)
+    if start >= 0 and end >= start:
+        end += len(MANAGED_END)
+        return f"{content[:start]}{managed}{content[end:]}"
+    if not content.strip():
+        return f"{managed}\n"
+    return f"{content.rstrip()}\n\n{managed}\n"
+
+
+def _root_block(agent: str) -> str:
+    import_line = {
+        "codex": "Read `.config/AGENTS/instructions.md` before changing code.",
+        "claude": "@.config/AGENTS/instructions.md",
+        "gemini": "@./.config/AGENTS/instructions.md",
+    }[agent]
+    return "\n".join(
+        (
+            "# IoP Agent Guidance",
+            "",
+            "This repository contains an IoP application.",
+            import_line,
+            "Use `build-iop-app` for application changes.",
+            "Use `validate-iop-app` for verification.",
+        )
+    )
+
+
+def _skill_wrapper(skill_name: str, description: str) -> str:
+    return (
+        "---\n"
+        f"name: {skill_name}\n"
+        f"description: {description}\n"
+        "---\n\n"
+        f"Read and follow `.config/AGENTS/skills/{skill_name}/SKILL.md`. "
+        "Load its referenced files only when the workflow calls for them.\n"
+    )

iop/ai/skills/build-iop-app/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: build-iop-app
+description: Build or modify an IoP application using production graphs, messages, components, tests, and all applicable bundled cookbooks. Use for new or changed Business Services, Business Processes, Business Operations, routes, settings, healthcare flows, or complete productions.
+---
+
+# Build An IoP Application
+
+Read `references/instructions.md`, then inspect the project README,
+`settings.py`, production graph, messages, components, tests, samples,
+dependency manifests, and Docker or Compose lifecycle files.
+
+## Workflow
+
+1. Establish the business goal, inbound and outbound systems, protocols,
+   routing or transformation behavior, runtime constraints, and acceptance
+   criteria. Infer repository facts before asking questions.
+2. Start with `references/cookbooks/index.md` and read every cookbook implicated
+   by the requested flow. Complete ingestion work normally requires the
+   ingestion-pipeline, polling-service, process, and operation cookbooks. Use
+   `code-index.md` when starting from source symbols.
+3. Write a short component-role plan before coding: identify the source
+   acquisition service, orchestration process, destination operations, messages,
+   and graph edges. A polling service fetches from its configured source and
+   emits data; a process validates, transforms, and routes it; an operation
+   performs persistence or another destination effect. Model complete ingestion
+   as `service -> process -> operation` unless a trivial pass-through is
+   explicitly justified.
+4. Implement through public `iop` imports. Use `target()` and graph connections
+   instead of direct component calls. Use `on_init()`, not `__init__()`, for
+   startup.
+5. Add focused tests and representative samples for each component boundary and
+   the production topology. Declare every directly imported third-party package
+   in the project's dependency manifest.
+6. Ensure the migration entrypoint exports the desired production through
+   `PRODUCTIONS` and remains safe to import. Preserve existing container
+   initialization, migration, health, and startup automation; update production
+   paths and names instead of disabling that lifecycle.
+7. Run the `validate-iop-app` skill. Do not deploy unless the user explicitly
+   requests it. A repository-owned disposable container is a validation
+   environment, not a shared deployment.
+
+For healthcare work, prefer native IRIS or Health Connect standards and
+transport components. Use the healthcare cookbooks for HL7v2 and FHIR choices.
+
+For an existing shared production, read the production change workflow and use
+plan/review/apply/verify instead of assuming the Python graph is a complete
+deployed-state replacement.
+
+## References
+
+- Core IoP rules: `references/instructions.md`
+- Task workflows: `references/cookbooks/index.md`
+- Existing production safety: `references/production-change-workflow.md`
+- Healthcare design: `references/healthcare-ai-coding.md`

iop/ai/skills/build-iop-app/references/agent-guidance.md

@@ -0,0 +1,69 @@
+# IoP Agent Guidance And Skills
+
+IoP ships version-matched project guidance, Agent Skills, and offline copies of
+the IoP cookbooks. Install them in any IoP application repository, including a
+project that was not created from the IoP template:
+
+```bash
+iop --install-agent-guidance
+```
+
+The command configures Codex, Claude Code, and Gemini CLI by default. It adds a
+small IoP-managed block to existing root instruction files without replacing
+other project rules, installs canonical guidance in `.config/AGENTS`, and adds
+the `build-iop-app` and `validate-iop-app` skills for each agent.
+
+## Select Agents
+
+Use one or more `--agent` options when the project only needs specific clients:
+
+```bash
+iop --install-agent-guidance --agent codex
+iop --install-agent-guidance --agent claude --agent gemini
+```
+
+Pass a project directory to configure a repository other than the current one:
+
+```bash
+iop --install-agent-guidance /path/to/iop-application
+```
+
+The installer is idempotent. If an IoP-managed file was changed locally, it
+stops before writing anything. Review the conflict, then replace only the
+IoP-managed snapshot when appropriate:
+
+```bash
+iop --install-agent-guidance --force-agent-guidance
+```
+
+Rerun that command after upgrading IoP to refresh the guides, skills, and
+offline cookbooks to the installed framework version.
+
+## Install Skills Directly
+
+Developers who only need the portable skills can install them from the IoP
+repository with the cross-agent Skills CLI:
+
+```bash
+npx skills add \
+  https://github.com/grongierisc/interoperability-embedded-python/tree/master/src/iop/ai/skills \
+  --skill build-iop-app \
+  --skill validate-iop-app
+```
+
+Direct installation provides the self-contained skills and their references.
+It does not add the always-on `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` project
+guidance; use the IoP installer when those entrypoints are wanted.
+
+## Skill Responsibilities
+
+- `build-iop-app` inspects the application, selects the relevant bundled
+  cookbook, and guides message, component, production graph, sample, and test
+  changes.
+- `validate-iop-app` runs project tests and strict migration dry-run first, then
+  requires container-backed runtime verification when the project provides a
+  disposable environment, while protecting shared or remote IRIS instances.
+
+The skill files use the shared Agent Skills `SKILL.md` format with only portable
+frontmatter. Client-specific wrappers contain no duplicated IoP policy; the
+installed `.config/AGENTS` snapshot remains the local source of truth.

iop/ai/skills/build-iop-app/references/cookbooks/add-business-operation.md

@@ -0,0 +1,130 @@
+# Cookbook: Add A BusinessOperation
+
+## When To Use This
+
+Use this cookbook when a production needs a destination side-effect boundary:
+calling a downstream API, writing a file, submitting FHIR, storing data, or
+wrapping a technical operation behind a production message. Acquisition from
+the configured source of a `PollingBusinessService` remains in that service;
+the operation receives the acquired or processed data.
+
+## Files You Will Touch
+
+- the operation module, such as `bo.py` or `operations.py`
+- the message module, such as `msg.py` or `messages.py`
+- `settings.py`
+- the fastest relevant test or sample payload
+
+## Prompt To Give Your Agent
+
+```text
+Add a new IoP BusinessOperation to this project.
+
+Business goal:
+<describe what the operation receives, validates, logs, transforms, or sends>
+
+Implementation requirements:
+- Reuse existing message classes if they already fit.
+- If a new message is needed, define it as a Message dataclass unless there is
+  a specific need for PersistentMessage.
+- Implement a fallback on_message(self, request) for simple operations, or route
+  by message type with typed one-argument methods or the @handler decorator.
+- Return a response message or the original request when that matches the flow.
+- Use self.log_info(), self.log_warning(), or self.log_error() for component
+  logging.
+- Do not add startup work to __init__(); use on_init() only if startup work is
+  required.
+- Update settings.py so the operation is added to the Production graph.
+- Add or update the fastest relevant test.
+- Show the exact verification command.
+```
+
+## Expected Implementation
+
+A simple operation can use `on_message()`:
+
+```python
+from iop import BusinessOperation
+
+from messages import OrderRequest, OrderResponse
+
+
+class OrderOperation(BusinessOperation):
+    def on_message(self, request: OrderRequest) -> OrderResponse:
+        self.log_info(f"Processing order {request.order_id}")
+        return OrderResponse(order_id=request.order_id, status="accepted")
+```
+
+When one operation handles multiple message types, prefer typed one-argument
+methods or the `@handler` decorator:
+
+```python
+from iop import BusinessOperation, handler
+
+from messages import CancelOrder, OrderRequest, OrderResponse
+
+
+class OrderOperation(BusinessOperation):
+    def on_message(self, request):
+        self.log_warning(f"Unhandled message {type(request).__name__}")
+        return request
+
+    def submit_order(self, request: OrderRequest) -> OrderResponse:
+        self.log_info(f"Submitting order {request.order_id}")
+        return OrderResponse(order_id=request.order_id, status="accepted")
+
+    @handler(CancelOrder)
+    def cancel_order(self, request):
+        self.log_info(f"Cancelling order {request.order_id}")
+        return request
+```
+
+IoP dispatches to:
+
+- a method decorated with `@handler(MessageType)` first
+- a typed one-argument method such as `submit_order(self, request: OrderRequest)`
+- `on_message(self, request)` as the fallback
+
+The production graph should register the operation:
+
+```python
+operation = prod.operation("OrderOperation", OrderOperation)
+```
+
+If another component sends to the operation, declare a `target()` setting on the
+sender and connect it:
+
+```python
+process = prod.process("OrderProcess", OrderProcess)
+process.connect(OrderProcess.Orders, operation)
+```
+
+## Migration Command
+
+```bash
+iop --migrate settings.py --dry-run
+iop --migrate settings.py
+```
+
+## Verification
+
+Use the fastest local test first:
+
+```bash
+python -m pytest
+```
+
+If there is no existing test suite, ask the agent to add a small test for the
+pure Python transformation or validation logic.
+
+## Common Mistakes
+
+- Creating an operation but not adding it to `settings.py`.
+- Combining source acquisition, orchestration, and destination persistence in
+  one operation.
+- Calling another production component as a normal Python object.
+- Hiding connection names in strings instead of using `target()` and
+  `prod.connect(...)`.
+- Using `PersistentMessage` when a regular `Message` dataclass is enough.
+- Adding multiple handlers for the same message type without making the
+  intended precedence explicit.

iop/ai/skills/build-iop-app/references/cookbooks/add-business-process.md

@@ -0,0 +1,115 @@
+# Cookbook: Add A BusinessProcess
+
+## When To Use This
+
+Use this cookbook when a production needs routing, orchestration, decision
+logic, enrichment, or coordination between services and operations.
+
+Business Processes should not own external side effects directly when a
+Business Operation is the better boundary. Keep the process focused on deciding
+what happens next and sending messages to downstream targets.
+
+## Files You Will Touch
+
+- the process module, such as `bp.py` or `processes.py`
+- the message module, such as `msg.py` or `messages.py`
+- operation modules only when downstream behavior is missing
+- `settings.py`
+- tests or sample payloads for routing decisions
+
+## Prompt To Give Your Agent
+
+```text
+Add a new IoP BusinessProcess to this project.
+
+Business goal:
+<describe the routing, orchestration, enrichment, or decision logic>
+
+Implementation requirements:
+- Reuse existing message classes if they already fit.
+- Declare outbound routes with target() attributes on the process class.
+- Route messages with send_request_sync(), send_request_async(), or direct
+  response behavior according to the existing project pattern.
+- Use on_message(self, request) for simple processes, or route by message type
+  with typed one-argument methods or the @handler decorator.
+- Keep external API calls, database writes, file writes, and FHIR submission in
+  BusinessOperation classes.
+- Do not add startup work to __init__(); use on_init() only if startup work is
+  required.
+- Update settings.py so the process is added to the Production graph and its
+  targets are connected.
+- Add or update tests for routing decisions.
+- Show the exact migration and verification commands.
+```
+
+## Expected Implementation
+
+A process declares outbound targets and sends messages to them:
+
+```python
+from iop import BusinessProcess, Message, handler, target
+
+from messages import OrderRequest, OrderResponse, RejectedOrder
+
+
+class OrderProcess(BusinessProcess):
+    Accepted = target()
+    Rejected = target()
+
+    def on_message(self, request):
+        self.log_warning(f"Unhandled message {type(request).__name__}")
+        return request
+
+    def route_order(self, request: OrderRequest):
+        if not request.order_id:
+            return self.send_request_sync(self.Rejected, RejectedOrder(reason="missing id"))
+
+        return self.send_request_sync(self.Accepted, request)
+
+    @handler(RejectedOrder)
+    def route_rejected(self, request):
+        self.log_info(request.reason)
+        return request
+```
+
+IoP dispatches to:
+
+- a method decorated with `@handler(MessageType)` first
+- a typed one-argument method such as `route_order(self, request: OrderRequest)`
+- `on_message(self, request)` as the fallback
+
+Wire the process in `settings.py`:
+
+```python
+process = prod.process("OrderProcess", OrderProcess)
+accepted = prod.operation("AcceptedOperation", AcceptedOperation)
+rejected = prod.operation("RejectedOperation", RejectedOperation)
+
+process.connect(OrderProcess.Accepted, accepted)
+process.connect(OrderProcess.Rejected, rejected)
+```
+
+## Migration Command
+
+```bash
+iop --migrate settings.py --dry-run
+iop --migrate settings.py
+```
+
+## Verification
+
+- Unit-test the routing decision with representative messages.
+- Dry-run migration shows the process and all target settings.
+- The production graph contains every expected process edge.
+- Runtime trace shows messages passing from service to process to operation.
+
+## Common Mistakes
+
+- Putting external API calls or database writes directly in the process.
+- Forgetting `target()` declarations for outbound routes.
+- Returning raw dictionaries instead of message objects when the downstream
+  component expects IoP messages.
+- Adding multiple handlers for the same message type without making the
+  intended precedence explicit.
+- Calling a downstream component directly instead of sending a production
+  message through a target.