iris-pex-embedded-python 4.0.0b11__tar.gz → 4.0.0b13__tar.gz

iris_pex_embedded_python-4.0.0b13/AGENTS.md

@@ -0,0 +1,101 @@
+# IoP Agent Guide
+
+This repository contains IoP, Interoperability On Python. IoP lets developers
+build InterSystems IRIS and Health Connect interoperability productions with
+Python components, messages, and production graphs.
+
+## Read First
+
+Before changing code or examples, read:
+
+- `README.md` for the package overview.
+- `docs/ai-coding.md` for AI-assisted coding guidance.
+- `docs/cookbooks/index.md` for task-specific app-building workflows.
+- `docs/cookbooks/code-index.md` when starting from source code.
+- `docs/getting-started/first-steps.md` for the preferred beginner workflow.
+- `docs/getting-started/register-component.md` for migration file structure.
+- `docs/production-graph.md` for Python-authored production definitions.
+- `docs/production-change-workflow.md` before changing existing IRIS
+  productions.
+
+## Project Map
+
+- `src/iop/components`: component base classes and component settings helpers.
+- `src/iop/messages`: message classes, serialization, validation, and dispatch.
+- `src/iop/production`: production graph, validation, rendering, diff, and
+  planning.
+- `src/iop/cli`: `iop` command-line parser, command dispatch, and formatting.
+- `src/iop/migration`: migration file loading, IRIS registration, and
+  production import/export utilities.
+- `src/iop/cls`: ObjectScript support classes packaged with IoP.
+- `demo/python`: runnable examples for common production patterns.
+- `src/tests/unit`: fast tests that should not require a live IRIS instance.
+- `src/tests/e2e`: IRIS-backed local and remote integration tests.
+
+## Coding Rules
+
+- For new applications, prefer a Python `Production` object exported through
+  `PRODUCTIONS` in `settings.py`.
+- Use `prod.service(...)`, `prod.process(...)`, `prod.operation(...)`, and
+  `prod.connect(...)` to declare topology.
+- Use `target()` on component classes for configurable outbound targets, then
+  connect those targets in the production graph.
+- Use `on_message(self, request)` as a simple fallback handler.
+- Use typed one-argument methods or `@handler(MessageType)` to route by message
+  type.
+- Do not put component startup logic in `__init__()`. IoP/IRIS allocates
+  components with `__new__()` and calls `on_init()` as the startup hook.
+- Use `on_tear_down()` for cleanup when a component becomes inactive.
+- Use `@dataclass` on regular `Message` classes. Do not decorate
+  `PydanticMessage` classes with `@dataclass`.
+- Use `PersistentMessage` only when a native persistent IRIS message body is
+  required.
+- Avoid raw `CLASSES` entries for new production components. Use `CLASSES` only
+  for standalone bindings or legacy migration files.
+- Keep executable sample code behind `if __name__ == "__main__":` when it lives
+  in a migration file, so migration can import `PRODUCTIONS` safely.
+- For app-building tasks, use the relevant cookbook in `docs/cookbooks/` before
+  writing code or examples.
+
+## Verification Commands
+
+Fast local checks:
+
+```bash
+python -m pytest src/tests/unit
+ruff check src
+pyright
+```
+
+Validate a migration file without writing to IRIS:
+
+```bash
+iop --migrate /path/to/settings.py --dry-run
+```
+
+Run the Docker-backed test suite:
+
+```bash
+docker build -t pytest-iris -f dockerfile-ci .
+docker run -i --rm pytest-iris
+```
+
+Build documentation:
+
+```bash
+mkdocs build
+```
+
+## IoP Production Best Practices
+
+- A production is a message graph.
+- Business Services are inbound entry points or triggers. They may be Python IoP
+  services or native IRIS services.
+- Business Processes orchestrate routing, decisions, transformations, and calls
+  to downstream components.
+- Business Operations isolate outbound side effects such as external APIs,
+  database writes, files, TCP, HTTP, or FHIR endpoints.
+- Components communicate through production messages and targets. Do not
+  instantiate another production component or call its methods directly.
+- For healthcare transports and standards, prefer native IRIS or Health Connect
+  components when they exist, then use Python for project-specific logic.

iris_pex_embedded_python-4.0.0b13/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include AGENTS.md
+include mkdocs.yml
+recursive-include docs *.md

{iris_pex_embedded_python-4.0.0b11/src/iris_pex_embedded_python.egg-info → iris_pex_embedded_python-4.0.0b13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris_pex_embedded_python
-Version: 4.0.0b11
+Version: 4.0.0b13
 Summary: Iris Interoperability based on Embedded Python
 Author-email: grongier <guillaume.rongier@intersystems.com>
 License: MIT License
@@ -63,6 +63,9 @@ Dynamic: license-file
 Welcome to the **Interoperability On Python (IoP)** proof of concept! This project demonstrates how the **IRIS Interoperability Framework** can be utilized with a **Python-first approach**.
 
 Documentation can be found [here](https://grongierisc.github.io/interoperability-embedded-python/).
+For prompt-driven workflows, see [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For task-oriented examples, see the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For application repositories, start from the [reusable AGENTS.md template](https://grongierisc.github.io/interoperability-embedded-python/agents-template/).
 
 ## Example
 
@@ -88,4 +91,8 @@ pip install iris-pex-embedded-python
 
 If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Python-authored production.
 
+If you are using an AI coding assistant, start with [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For concrete workflows, use the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For healthcare productions, also see [Healthcare AI-assisted coding](https://grongierisc.github.io/interoperability-embedded-python/healthcare-ai-coding/).
+
 Happy coding!

{iris_pex_embedded_python-4.0.0b11 → iris_pex_embedded_python-4.0.0b13}/README.md

@@ -9,6 +9,9 @@
 Welcome to the **Interoperability On Python (IoP)** proof of concept! This project demonstrates how the **IRIS Interoperability Framework** can be utilized with a **Python-first approach**.
 
 Documentation can be found [here](https://grongierisc.github.io/interoperability-embedded-python/).
+For prompt-driven workflows, see [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For task-oriented examples, see the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For application repositories, start from the [reusable AGENTS.md template](https://grongierisc.github.io/interoperability-embedded-python/agents-template/).
 
 ## Example
 
@@ -34,4 +37,8 @@ pip install iris-pex-embedded-python
 
 If you're new to this project, begin by reading the [installation guide](https://grongierisc.github.io/interoperability-embedded-python/getting-started/installation). Then, follow the [first steps](https://grongierisc.github.io/interoperability-embedded-python/getting-started/first-steps) to create your first Python-authored production.
 
+If you are using an AI coding assistant, start with [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
+For concrete workflows, use the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
+For healthcare productions, also see [Healthcare AI-assisted coding](https://grongierisc.github.io/interoperability-embedded-python/healthcare-ai-coding/).
+
 Happy coding!

iris_pex_embedded_python-4.0.0b13/docs/agents-template.md

@@ -0,0 +1,151 @@
+# Reusable AGENTS.md For IoP Projects
+
+Copy this template into the root of an application repository as `AGENTS.md`.
+Keep it generic. Put project-specific details in the project README or in a
+short project brief section.
+
+````md
+# Agent Guide
+
+This project is an IoP application. IoP means Interoperability On Python: a
+Python-first way to build InterSystems IRIS and Health Connect interoperability
+productions.
+
+## First Prompt Contract
+
+Before major implementation, make sure the project goal is explicit. If any of
+these details are missing, ask for them or infer only when the repository makes
+the answer clear:
+
+- Business goal:
+- Inbound systems:
+- Outbound systems:
+- Data standards or protocols:
+- Required routing or transformation behavior:
+- Runtime constraints:
+- Acceptance criteria:
+
+## Read First
+
+Before changing code, read:
+
+- `README.md` for setup and project-specific workflow.
+- `settings.py`, `production.py`, or `prod.py` for the IoP `Production` graph.
+- the relevant IoP cookbook, if present in this repository.
+- message definitions such as `messages.py` or `msg.py`.
+- components such as `bs.py`, `bp.py`, `bo.py`, `services.py`, `processes.py`,
+  or `operations.py`.
+- existing tests, fixtures, and sample payloads.
+
+If this project does not include local cookbooks, use the public IoP cookbooks:
+<https://grongierisc.github.io/interoperability-embedded-python/cookbooks/>
+
+## Project Map
+
+Update this list for the local project:
+
+- `settings.py`: migration entrypoint with `PRODUCTIONS = [prod]`.
+- `production.py` or `prod.py`: Python production graph definition.
+- `messages.py` or `msg.py`: Python message classes.
+- `bs.py` or `services.py`: Python Business Services.
+- `bp.py` or `processes.py`: Python Business Processes.
+- `bo.py` or `operations.py`: Python Business Operations.
+- `tests/`: local test suite.
+- `data/` or `samples/`: example payloads.
+
+## IoP Rules
+
+- Prefer a Python `Production` object exported through `PRODUCTIONS`.
+- Use `prod.service(...)`, `prod.process(...)`, `prod.operation(...)`, and
+  `prod.connect(...)` to declare topology.
+- Use `target()` on component classes for configurable outbound targets.
+- Do not put component startup logic in `__init__()`. Use `on_init()`.
+- Use `on_tear_down()` for cleanup when a component becomes inactive.
+- Use `@dataclass` on regular `Message` classes. Do not decorate
+  `PydanticMessage` classes with `@dataclass`.
+- Use `PersistentMessage` only when IRIS needs a native persistent message body.
+- Avoid raw `CLASSES` entries for components already declared in the production
+  graph.
+- Keep executable sample code behind `if __name__ == "__main__":` when it lives
+  in a migration file.
+
+## Dispatch Rules
+
+- Use `on_message(self, request)` as a simple fallback handler.
+- Use typed one-argument methods to route by message type, for example
+  `submit_order(self, request: OrderRequest)`.
+- Use `@handler(MessageType)` when the handler should be explicit or the type
+  annotation is not enough.
+- Avoid duplicate handlers for the same message type unless the intended
+  precedence is clear.
+
+## Production Design Rules
+
+- A production is a message graph.
+- Business Services are inbound entry points or triggers. They may be Python IoP
+  services or native IRIS services.
+- Business Processes orchestrate routing, decisions, transformations, and calls
+  to downstream components.
+- Business Operations isolate outbound side effects such as external APIs,
+  database writes, files, TCP, HTTP, or FHIR endpoints.
+- Components communicate through production messages and targets. Do not
+  instantiate another production component or call its methods directly.
+
+## Add-ons
+
+Use add-ons only when the project needs them:
+
+- Healthcare standards such as HL7v2 or FHIR:
+  <https://grongierisc.github.io/interoperability-embedded-python/healthcare-ai-coding/>
+- HL7v2 native input:
+  <https://grongierisc.github.io/interoperability-embedded-python/cookbooks/hl7v2-native-input/>
+- HL7v2 to FHIR with fhir-converter:
+  <https://grongierisc.github.io/interoperability-embedded-python/cookbooks/hl7v2-to-fhir-with-fhir-converter/>
+- FHIR submission with a Python client:
+  <https://grongierisc.github.io/interoperability-embedded-python/cookbooks/fhir-submission-python-client/>
+
+## Definition Of Done
+
+A change is done when the fastest relevant checks pass and the expected
+production behavior is observable. Adapt this list to the local project:
+
+```bash
+python -m pytest
+iop --migrate settings.py --dry-run
+iop --migrate settings.py
+```
+
+If this repository uses Docker or Compose, add the exact command here:
+
+```bash
+docker compose up --build
+```
+
+For production behavior, verify at least one of:
+
+- production starts and reports running status
+- expected output file, API call, database write, FHIR resource, or message is
+  observable
+- logs show service/process/operation execution with no blocking errors
+- Message Viewer or queue status shows the expected flow
+
+## Troubleshooting Prompts
+
+When diagnosing a failure, report:
+
+- exact command that failed
+- traceback or IRIS error
+- files read before changing code
+- smallest suspected failure boundary: Python, migration, IRIS runtime,
+  external dependency, or test data
+
+## Expected AI Output
+
+For every non-trivial change, include:
+
+- updated files list
+- short rationale for behavior change
+- exact commands used to verify
+- test results summary
+- residual risk or follow-up item
+````

iris_pex_embedded_python-4.0.0b13/docs/ai-coding.md

@@ -0,0 +1,83 @@
+# AI-Assisted Coding With IoP
+
+Use this guide when you want to vibe code with IoP while still getting
+production-shaped, reviewable Python interoperability code.
+
+## Start Here
+
+Ask the tool to read the project guidance before it writes code:
+
+```text
+You are helping me build an IoP application.
+Read these files first:
+- AGENTS.md
+- docs/ai-coding.md
+- docs/cookbooks/index.md
+- docs/getting-started/first-steps.md
+- docs/getting-started/register-component.md
+- docs/production-graph.md
+
+Use the Python Production graph workflow for new applications.
+Do not put component startup logic in __init__(); use on_init().
+Use the relevant cookbook for the task.
+Show the migration and verification commands.
+```
+
+On the published docs site, open
+[AGENTS.md](https://github.com/grongierisc/interoperability-embedded-python/blob/master/AGENTS.md)
+from the repository root.
+
+For your own IoP application repository, copy the
+[reusable AGENTS.md template](agents-template.md) into the project root and
+adapt it to the local production. For healthcare projects, also read
+[Healthcare AI-assisted coding](healthcare-ai-coding.md).
+
+## Cookbooks
+
+Use the [IoP cookbooks](cookbooks/index.md) for task-specific prompts and
+checklists:
+
+- [Hello-world production](cookbooks/hello-world-production.md)
+- [Code index for agents](cookbooks/code-index.md)
+- [Add a BusinessOperation](cookbooks/add-business-operation.md)
+- [Add a BusinessProcess](cookbooks/add-business-process.md)
+- [Add a PollingBusinessService](cookbooks/add-polling-service.md)
+- [Production settings and targets](cookbooks/production-settings-and-targets.md)
+- [Remote migration](cookbooks/remote-migration.md)
+- [HL7v2 native input](cookbooks/hl7v2-native-input.md)
+- [HL7v2 to FHIR with fhir-converter](cookbooks/hl7v2-to-fhir-with-fhir-converter.md)
+- [FHIR submission with a Python client](cookbooks/fhir-submission-python-client.md)
+
+## Good Output Expectations
+
+For a new IoP application, generated code should include:
+
+- a `settings.py` file with a `Production` object
+- `PRODUCTIONS = [prod]`
+- clear component names such as `FileService`, `RouteProcess`, or
+  `OrderOperation`
+- message classes for data exchanged between components
+- `target()` settings for configurable outbound routing
+- `prod.connect(...)` calls that wire services, processes, and operations
+- sample payloads or tests when behavior changes
+- migration and verification commands
+
+## Useful Commands
+
+```bash
+# Fast pure-Python checks
+python -m pytest src/tests/unit
+
+# Validate a migration file without writing to IRIS
+iop --migrate settings.py --dry-run
+
+# Migrate a production
+iop --migrate settings.py
+
+# Build the documentation
+mkdocs build
+
+# Run the Docker-backed suite
+docker build -t pytest-iris -f dockerfile-ci .
+docker run -i --rm pytest-iris
+```

iris_pex_embedded_python-4.0.0b13/docs/benchmarks.md

@@ -0,0 +1,27 @@
+# Benchmarks
+
+24 scenarios with these parameters:
+- 100 messages
+- body: simple string `test`
+
+The benchmark matrix covers these routes:
+- Python BP to Python BO
+- Python BP to ObjectScript BO
+- ObjectScript BP to Python BO
+- ObjectScript BP to ObjectScript BO
+
+Each route is tested with these message types:
+- IRIS `Ens.StringRequest`
+- `Message`
+- `PydanticMessage`
+- `PersistentMessage`
+- `PickleMessage`
+- `PydanticPickleMessage`
+
+The test writes current timing results to `src/tests/e2e/local/bench/result.txt`.
+
+Benchmarks can be run in the unit test with the following command :
+
+```bash
+PYTHONPATH=src pytest src/tests/e2e/local/test_bench.py
+```

iris_pex_embedded_python-4.0.0b13/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

iris_pex_embedded_python-4.0.0b13/docs/code-of-conduct.md

@@ -0,0 +1,3 @@
+# Code of conduct
+
+TODO