mloda-plugin-jev 0.2.1__tar.gz

mloda_plugin_jev-0.2.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mloda_plugin_jev-0.2.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: mloda-plugin-jev
+Version: 0.2.1
+Summary: mloda plugin that runs Jev: typed answers about a text column as feature columns
+Author-email: Tom Kaltofen <tomkaltofen@mloda.ai>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/mloda-ai/mloda-plugin-jev
+Project-URL: Documentation, https://github.com/mloda-ai/mloda-plugin-jev#readme
+Project-URL: Issues, https://github.com/mloda-ai/mloda-plugin-jev/issues
+Project-URL: Changelog, https://github.com/mloda-ai/mloda-plugin-jev/releases
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mloda<0.14.0,>=0.13.0
+Requires-Dist: typesafe-sdk>=0.7.0
+Requires-Dist: httpx2>=2.0.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: observability
+Requires-Dist: mloda-community-otel>=0.4.7; extra == "observability"
+Requires-Dist: mloda-community-openlineage>=0.4.7; extra == "observability"
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: tox-uv; extra == "dev"
+Requires-Dist: uv>=0.11.6; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: bandit; extra == "dev"
+Requires-Dist: mloda-testing[openlineage,otel]>=0.4.7; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: polars; extra == "dev"
+Requires-Dist: pyarrow; extra == "dev"
+Provides-Extra: demo
+Requires-Dist: marimo>=0.24.2; extra == "demo"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=4.0.3; extra == "mcp"
+Requires-Dist: fastapi>=0.141.1; extra == "mcp"
+Requires-Dist: uvicorn>=0.52.4; extra == "mcp"
+Dynamic: license-file
+
+# mloda-plugin-jev
+
+An [mloda](https://github.com/mloda-ai/mloda) plugin that runs [Jev](https://docs.typesafe.ai) as a FeatureGroup: ask typed questions about a text column and get the answers back as feature columns.
+
+## Install
+
+```bash
+pip install mloda-plugin-jev
+export TYPESAFE_API_KEY=...
+```
+
+## Example
+
+```python
+from mloda.user import Feature, Options, PluginLoader, mloda
+from mloda_plugins.compute_framework.base_implementations.python_dict.python_dict_framework import PythonDictFramework
+
+PluginLoader.all()
+
+urgent = {"type": "noul", "instructions": "The message conveys urgency"}
+
+result = mloda.run_all(
+    [Feature("ticket__jev_urgent", Options(context={"jev_question": urgent}))],
+    compute_frameworks={PythonDictFramework},
+    api_data={"Tickets": {"ticket": ["I was charged twice, please fix ASAP", "The login page is broken"]}},
+)
+print(result[0]["ticket__jev_urgent"])  # for example [0.97, 0.12]: the probability of yes per row
+```
+
+The full documentation, including the `mloda` command line, is in the [README on GitHub](https://github.com/mloda-ai/mloda-plugin-jev#readme).

mloda_plugin_jev-0.2.1/README.md

@@ -0,0 +1,243 @@
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![mloda](https://img.shields.io/badge/built%20with-mloda-blue.svg)](https://github.com/mloda-ai/mloda)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![Tests](https://github.com/mloda-ai/mloda-plugin-jev/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mloda-ai/mloda-plugin-jev/actions/workflows/test.yml?query=branch%3Amain)
+
+# mloda-plugin-jev
+
+> An [mloda](https://github.com/mloda-ai/mloda) plugin that runs [Jev](https://docs.typesafe.ai) as a FeatureGroup: ask typed questions about a text column and get the answers back as feature columns.
+
+Jev is TypeSafe AI's non-generative decision model. You give it text and typed questions, and it returns typed answers with probabilities instead of generated text. This plugin sends each row of a text column to Jev and turns every question into a result column.
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install mloda-plugin-jev
+```
+
+The `observability` extra adds the [Observability](#observability) extenders: `pip install "mloda-plugin-jev[observability]"`. For the development version, use `pip install git+https://github.com/mloda-ai/mloda-plugin-jev`. To work on the code, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Set your TypeSafe API key:
+
+```bash
+export TYPESAFE_API_KEY=...
+```
+
+## Usage
+
+```python
+from mloda.user import Feature, Options, PluginLoader, mloda
+from mloda_plugins.compute_framework.base_implementations.python_dict.python_dict_framework import PythonDictFramework
+
+PluginLoader.all()  # discover this plugin through its entry points
+
+department = {
+    "type": "choice",
+    "instructions": "Which team should handle this?",
+    "criteria": {"billing": "Payments and invoices", "technical": "Bugs and outages"},
+}
+urgent = {"type": "noul", "instructions": "The message conveys urgency"}
+
+result = mloda.run_all(
+    [
+        Feature("ticket__jev_department", Options(context={"jev_question": department})),
+        Feature("ticket__jev_urgent", Options(context={"jev_question": urgent})),
+    ],
+    compute_frameworks={PythonDictFramework},
+    api_data={"Tickets": {"ticket": ["I was charged twice, please fix ASAP", "The login page is broken"]}},
+    column_ordering="request_order",
+)
+for name, values in result[0].items():
+    print(name, values)
+```
+
+For example, this prints one column per requested feature (the values come from Jev):
+
+```text
+ticket__jev_department ['billing', 'technical']
+ticket__jev_urgent [0.97, 0.12]
+```
+
+A feature is named `<text_column>__jev_<question_name>`. The text column is the input feature, and the question goes in the `jev_question` context option in Jev's own shape. Null, empty and whitespace-only text stays `None` and makes no call.
+
+| Question `type` | `criteria` | Result column | With `jev_details=True`, also |
+| --- | --- | --- | --- |
+| `choice` | Labels mapped to descriptions | The chosen label (`str`) | `~confidence` (`float`, 0 to 1) and `~probabilities` (label to probability) |
+| `score` | A list of rubric level descriptions | The expected score (`float`, can fall between levels) | `~confidence` and `~probabilities` (level `"0"`, `"1"`, ... to probability) |
+| `noul` | Optional descriptions of the yes and no outcomes | The probability of yes, 0 to 1 (`float`) | nothing: the value is a probability already |
+
+`jev_details=True` adds the columns `ticket__jev_department~confidence` and `ticket__jev_department~probabilities` next to `ticket__jev_department`, from the same call, so a low confidence can send a row to a human. mloda returns them with the feature; they cannot be requested on their own. The probabilities are a dict per row (a struct in PyArrow and Polars).
+
+The feature group runs on `PythonDictFramework`, `PandasDataFrame`, `PolarsDataFrame` and `PyArrowTable`, and returns the frame it was given with the result columns added: strings for `choice`, floats (`NaN` in pandas) for `score` and `noul`. Name the framework in `compute_frameworks`: without it, mloda picks one of those that are installed, so the result type depends on the environment.
+
+See the Jev docs for [choice](https://docs.typesafe.ai/primitives/choice), [score](https://docs.typesafe.ai/primitives/score) and [noul](https://docs.typesafe.ai/primitives/noul).
+
+Several features can share one question book instead of carrying a question each. `jev_questions` maps question names to questions, and the name in the feature picks the entry, so `ticket__jev_department` asks the question called `department`. A name the book does not hold fails when mloda resolves the feature, before any call. A feature's own `jev_question` wins over the book.
+
+```python
+book = Options(context={"jev_questions": {"department": department, "urgent": urgent}})
+features = [Feature("ticket__jev_department", book), Feature("ticket__jev_urgent", book)]
+```
+
+## Command line
+
+Installing the package also installs a `mloda` command, and `uvx --from mloda-plugin-jev mloda --help` runs it without installing. The feature name is the whole interface:
+
+```bash
+mloda ticket ticket__jev_urgent --file tickets.csv -o jev_questions:=@questions.json
+```
+
+With the data and the questions in a `mloda.toml`, that becomes `mloda ticket__jev_urgent`. See [docs/cli.md](docs/cli.md).
+
+**This package installs the `mloda` and `mloda-mcp` commands.** They are plugin-agnostic and ship from here until mloda core has its own ([mloda#1592](https://github.com/mloda-ai/mloda/issues/1592)). Commands do not merge: another package that declares `mloda` overwrites it without a warning, and uninstalling either package removes it.
+
+## MCP server
+
+The `mcp` extra adds `mloda-mcp`, the same command as an [MCP](https://modelcontextprotocol.io) server for agents, built with FastMCP and FastAPI:
+
+```bash
+pip install '.[mcp]'
+mloda-mcp --allow-option jev_question    # http://127.0.0.1:8000/mcp
+```
+
+An agent lists the feature groups, explains a request for free, and runs it. Callers cannot name files, and they can set only the options you allow. There is no authentication, so read [docs/mcp.md](docs/mcp.md) before you expose it.
+
+## Options
+
+Every setting of the [`typesafe-sdk`](https://github.com/typesafe-ai/typesafe-sdk-python) client is an optional context option. Leave one out to use the SDK default.
+
+| Option | SDK argument | What it does |
+| --- | --- | --- |
+| `jev_api_key` | `TypeSafeClient(api_key=)` | API key. Prefer the `TYPESAFE_API_KEY` environment variable, because option values show up in logs and reprs. |
+| `jev_base_url` | `TypeSafeClient(base_url=)` | API root (environment variable `TYPESAFE_BASE_URL`). |
+| `jev_headers` | `TypeSafeClient(headers=)` | Extra headers on every request. |
+| `jev_transport` | `TypeSafeClient(transport=)` | Custom `httpx2` transport. Mutually exclusive with `jev_http_client`. |
+| `jev_http_client` | `TypeSafeClient(http_client=)` | Custom `httpx2.Client`. |
+| `jev_model` | `system_one(model=)` | Model name. Defaults to `jev-latest` (environment variable `TYPESAFE_DEFAULT_MODEL`). |
+| `jev_retry` | `system_one(retry=)` | A `RetryPolicy` or a dict of its fields, for example `{"max_retries": 0}`. The SDK retries twice by default. |
+| `jev_timeout` | `system_one(timeout=)` | Timeout in seconds, or an `httpx2.Timeout`. |
+| `jev_extra_headers` | `system_one(extra_headers=)` | Extra headers for the call. |
+| `jev_extra_body` | `system_one(extra_body=)` | Extra top-level request body fields. |
+| `jev_on_error` | none, a plugin setting | `raise` (default) fails the run when a Jev call fails. `skip` leaves that row `None`, keeps the other rows' answers and emits a `RowFailureWarning`. |
+| `jev_concurrency` | none, a plugin setting | Calls in flight at a time, default `1`. Rows keep their order. With `raise`, no new call starts after a failed one. |
+| `jev_deduplicate` | none, a plugin setting | `True` sends identical texts once and gives each of their rows the answer. Off by default: Jev does not promise the same answer for the same text. Features that differ in it get separate calls. |
+| `jev_details` | none, a plugin setting | `True` adds `~confidence` and `~probabilities` columns to a `choice` or `score` feature, see [Usage](#usage). |
+
+Features that share a text column **and** the same settings are answered in one Jev call per row. Features with different settings (for example different models) get separate calls. `jev_concurrency` and `jev_details` do not split calls: a batch runs at the highest `jev_concurrency` of its features. On the command line, pass numbers and flags as JSON, for example `-o jev_concurrency:=8 -o jev_details:=true`: with plain `=` the value is a string, and the error names the option and what it expects.
+
+A run that skips rows still reports success to the extenders, and `python -W error` turns the warning into a failure of the whole run, so collect it explicitly:
+
+```python
+import warnings
+
+from mloda_plugin_jev.row_failure import RowFailureWarning
+
+with warnings.catch_warnings(record=True) as caught:
+    warnings.simplefilter("always")
+    result = mloda.run_all(...)  # the features carry jev_on_error="skip" in their context options
+failed = [w.message for w in caught if isinstance(w.message, RowFailureWarning)]  # .column, .rows (0-based), .reason
+```
+
+**Pin the model for stable results.** `jev-latest` is an alias that moves when a new release ships. At the time of writing it resolves to `jev-1.13.0`, so `jev_model="jev-1.13.0"` keeps results from changing under you.
+
+## Observability
+
+Jev runs work with the OpenTelemetry and OpenLineage extenders from [mloda-registry](https://github.com/mloda-ai/mloda-registry). The `observability` extra installs them (`mloda-community-otel` and `mloda-community-openlineage`). Add them to the `run_all` call from Usage:
+
+```python
+from mloda.community.extenders.openlineage import OpenLineageExtender
+from mloda.community.extenders.otel import OtelExtender
+
+result = mloda.run_all(
+    ...,  # the arguments from Usage
+    function_extender={OtelExtender(use_sdk_defaults=True), OpenLineageExtender(use_sdk_defaults=True)},
+)
+```
+
+`use_sdk_defaults=True` uses the global OpenTelemetry tracer provider and OpenLineage's own configuration (for example `OPENLINEAGE_URL` or `OPENLINEAGE_CONFIG`). You can inject `tracer_provider=` or `client=` instead. With neither, the extender does nothing and logs a warning.
+
+- **OpenTelemetry:** the extra installs the API only. Your application has to install and configure an OpenTelemetry SDK with an exporter. Without one, `use_sdk_defaults=True` emits no spans and logs no warning.
+- **OpenLineage:** with no configuration the client falls back to its console transport and logs every event at INFO. `OPENLINEAGE_DISABLED=true` turns it off.
+
+| Extender | What a Jev calculation emits |
+| --- | --- |
+| `OtelExtender` | One `mloda.calculate` span for the whole batch (not one per row) with the feature group name and version, rows in and out, and the run id, plus a `mloda.validate.input` and a `mloda.validate.output` span. A failed call sets the status to `ERROR` and `error.type`, except for a row skipped with `jev_on_error="skip"`. |
+| `OpenLineageExtender` | A `START` and a `COMPLETE` (or `FAIL`, but not for a skipped row) event for the Jev job, with one output dataset and its type per question column. The events list no inputs: the text column is tied to the job through the shared parent run only. |
+
+The feature group name in spans and the job name in events are the full path, `mloda_plugin_jev.feature_groups.decision.jev_feature_group.JevFeatureGroup`.
+
+**A span per Jev call.** The plugin itself (not an extender) opens a `jev.system_one` span of kind `CLIENT` for every call actually made: none for a blank row, and one for texts that `jev_deduplicate` sends once. It carries `jev.question.count`, `jev.request.model` (only when `jev_model` is set), `jev.response.model` (the model that answered, so a `jev-latest` result can be reproduced) and, when the API reports them, `jev.usage.input_tokens` and `jev.usage.output_tokens`. A failed call sets the status to `ERROR` and `error.type`. SDK retries happen inside the span. A failure in the tracing code is logged at WARNING and never fails a call.
+
+- These spans need the OpenTelemetry API from the `observability` extra (without it nothing is recorded) and are recorded whenever the application sets a global OpenTelemetry SDK tracer provider, with or without an extender. A `tracer_provider=` injected into the extender does not receive them. They nest under the current span, the extender's `mloda.calculate` when it is used, and are root traces otherwise.
+- A large file makes many spans, so sample at the SDK.
+- Spans and events carry metadata only, the `jev.system_one` spans included: no API key, question, text or error message. When a call fails, the extenders log the error message at WARNING, like mloda itself.
+- Keep `capture_content` and `MLODA_OTEL_TRACE_CONTENT` off for sensitive text, or pass a `mask`: the content preview includes the text column.
+- Both extenders default to `raise_on_error=False`, so a telemetry failure never fails a Jev run. Events are sent on the calculation thread, so a slow or unreachable endpoint still slows the run.
+
+See the [extender guide](https://github.com/mloda-ai/mloda-registry/blob/main/docs/guides/11-create-extender.md) for sink resolution and multiprocessing.
+
+## Demo notebooks
+
+These [marimo](https://marimo.io) notebooks show Jev's typed columns:
+
+| Notebook | Story |
+| --- | --- |
+| [`demo/support_triage.py`](demo/support_triage.py) | Seven support tickets and an empty row become team queues and an on-call page. Questions share one call per row, so a new question adds a column without adding calls. |
+| [`demo/rag_context_gate.py`](demo/rag_context_gate.py) | Eight retrieved chunks get typed questions each, and plain Python decides which ones reach the LLM prompt. |
+| [`demo/pre_send_gate.py`](demo/pre_send_gate.py) | Draft client messages get typed answers with the model pinned. Plain Python holds or sends each one, and every decision is recorded as a JSON line that a re-check can compare. |
+| [`demo/churn_digest.py`](demo/churn_digest.py) | App reviews get typed answers, and plain Python turns them into a per-plan table with an alert line. An illustration of the pattern, not a churn metric. |
+
+From a clone:
+
+```bash
+uv sync --all-extras
+marimo edit demo/support_triage.py
+```
+
+The notebooks run offline by default: `demo/offline_jev.py` answers from keyword rules through the `jev_transport` option, so they show the pipeline, not model quality. Set `JEV_DEMO_LIVE=1` and `TYPESAFE_API_KEY` to call the real model; the synthetic notebook texts are then sent to the Jev API.
+
+## Limits
+
+- Runs on the python dict, pandas, Polars and PyArrow frameworks only (not Polars lazy frames, DuckDB, SQLite or Spark).
+- One request per row with text, sent one after another unless `jev_concurrency` is set. Jev's documented rate limit is 1,200 requests per minute (20 per second): size `jev_concurrency` so that it holds. A failed call fails the run unless `jev_on_error` is `skip`.
+- The text plus the longest question must fit in 32k tokens. Input is text only.
+
+## Project layout
+
+```text
+mloda_plugin_jev/
+├── cli.py                   # the mloda command, plugin-agnostic
+├── mcp_server.py            # the mloda-mcp server, built on cli.py
+├── row_failure.py           # RowFailureWarning, the report of rows that got no answer
+└── feature_groups/
+    ├── manifest.py          # entry-point manifest: FEATURE_GROUPS
+    └── decision/            # JevFeatureGroup and its tests
+```
+
+`cli.py`, `mcp_server.py` and `row_failure.py` import nothing else from the package, so they can move to mloda core as they are. `pyproject.toml` wires `manifest.py` up under `[project.entry-points."mloda.feature_groups"]`, which is how `PluginLoader.all()` finds the plugin. To add a FeatureGroup, append it to `FEATURE_GROUPS`.
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, and follow the [Code of Conduct](CODE_OF_CONDUCT.md). Report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+## Development
+
+From a clone, set up the virtualenv as in [CONTRIBUTING.md](CONTRIBUTING.md#local-development-setup), then:
+
+```bash
+source .venv/bin/activate
+tox
+```
+
+`tox` is the gate: `pytest`, `ruff format --check`, `ruff check`, `mypy --strict` and `bandit`. Run `tox -e security` for a `pip-audit` CVE scan. Commits follow [Conventional Commits](https://www.conventionalcommits.org/), which drives the release versioning. See [AGENTS.md](AGENTS.md) for the project practices.
+
+- [docs/github-workflows.md](docs/github-workflows.md): the CI and release workflows and their secrets.
+- [docs/github-repository-settings.md](docs/github-repository-settings.md): branch protection and required checks.
+
+## Related
+
+- [mloda](https://github.com/mloda-ai/mloda): the core library.
+- [mloda-registry plugin guides](https://github.com/mloda-ai/mloda-registry/tree/main/docs/guides/): how to write FeatureGroups, ComputeFrameworks and Extenders.
+- [Jev docs](https://docs.typesafe.ai): the model, the primitives and the API.

mloda_plugin_jev-0.2.1/README_PYPI.md

@@ -0,0 +1,30 @@
+# mloda-plugin-jev
+
+An [mloda](https://github.com/mloda-ai/mloda) plugin that runs [Jev](https://docs.typesafe.ai) as a FeatureGroup: ask typed questions about a text column and get the answers back as feature columns.
+
+## Install
+
+```bash
+pip install mloda-plugin-jev
+export TYPESAFE_API_KEY=...
+```
+
+## Example
+
+```python
+from mloda.user import Feature, Options, PluginLoader, mloda
+from mloda_plugins.compute_framework.base_implementations.python_dict.python_dict_framework import PythonDictFramework
+
+PluginLoader.all()
+
+urgent = {"type": "noul", "instructions": "The message conveys urgency"}
+
+result = mloda.run_all(
+    [Feature("ticket__jev_urgent", Options(context={"jev_question": urgent}))],
+    compute_frameworks={PythonDictFramework},
+    api_data={"Tickets": {"ticket": ["I was charged twice, please fix ASAP", "The login page is broken"]}},
+)
+print(result[0]["ticket__jev_urgent"])  # for example [0.97, 0.12]: the probability of yes per row
+```
+
+The full documentation, including the `mloda` command line, is in the [README on GitHub](https://github.com/mloda-ai/mloda-plugin-jev#readme).

mloda_plugin_jev-0.2.1/mloda_plugin_jev/__main__.py

@@ -0,0 +1,4 @@
+from mloda_plugin_jev.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())