jevframe 0.1.0__tar.gz

jevframe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run marimo check --strict examples/reviews.py
+      - run: uv build

jevframe-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Install test dependencies
+        run: uv sync --locked --all-extras
+      - name: Check release version
+        if: github.ref_type == 'tag'
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          uv run --no-sync python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          assert os.environ["RELEASE_TAG"] == f"v{version}", "Tag must match package version"
+          PY
+      - name: Test and check the notebook
+        run: |
+          uv run --no-sync pytest -q
+          uv run --no-sync ruff check .
+          uv run --no-sync ruff format --check .
+          uv run --no-sync marimo check --strict examples/reviews.py
+      - name: Build distributions
+        run: uv build --no-sources
+      - name: Validate package metadata
+        run: uvx --from twine twine check --strict dist/*
+      - name: Check isolated imports from both distributions
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python -c 'import jevframe'
+          uv run --isolated --no-project --with dist/*.tar.gz python -c 'import jevframe'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/jevframe/
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish using the GitHub identity
+        run: uv publish --trusted-publishing always

jevframe-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.env
+__marimo__/

jevframe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantin Taletskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jevframe-0.1.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.5
+Name: jevframe
+Version: 0.1.0
+Summary: Typed semantic decisions for pandas and Polars with TypeSafe Jev
+Project-URL: Repository, https://github.com/ktaletsk/jevframe
+Project-URL: Issues, https://github.com/ktaletsk/jevframe/issues
+Author: Konstantin Taletskiy
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tqdm<5,>=4.66
+Requires-Dist: typesafe-sdk<0.8,>=0.7
+Provides-Extra: examples
+Requires-Dist: altair<7,>=5; extra == 'examples'
+Requires-Dist: marimo<1,>=0.19; extra == 'examples'
+Requires-Dist: pandas<4,>=2.2; extra == 'examples'
+Provides-Extra: pandas
+Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars<2,>=1; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# jevframe
+
+[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/ktaletsk/jevframe/blob/main/examples/reviews.py)
+
+Ask the same semantic questions about every row of a dataframe using
+[TypeSafe Jev](https://docs.typesafe.ai/). Get ordinary pandas or Polars results,
+with bounded async inference and complete probability distributions.
+
+## Install
+
+```sh
+uv add 'jevframe[pandas]==0.1.0'     # in your uv project
+# Or: uv add 'jevframe[polars]==0.1.0' / 'jevframe[pandas,polars]==0.1.0'
+export TYPESAFE_API_KEY='your-key'
+```
+
+Python 3.10+; the official `typesafe-sdk>=0.7,<0.8` handles inference. Dataframe
+dependencies are optional. Importing an integration registers its `.jev` accessor.
+
+On **molab**, open the notebook's **Secrets** sidebar panel and add
+`TYPESAFE_API_KEY` with your key as its value. molab loads it automatically and
+persists it between sessions; `.env` secrets are excluded from forks.
+[Molab's secrets documentation](https://marimo.io/pages/molab/storage#secrets-stay-with-your-notebook).
+Then click **Evaluate reviews** in the demo. You do not need to put the key in a code cell.
+
+## pandas
+
+These examples use notebook top-level `await`. In a script, put them inside an
+`async def main()` and call `asyncio.run(main())`.
+
+```python
+import pandas as pd
+import jevframe.pandas
+from typesafe_sdk import Choice, Noul
+
+df = pd.DataFrame(
+    {
+        "title": ["Charged twice", "Great update"],
+        "review": ["Please refund the duplicate charge today.", "Everything works well!"],
+    }
+)
+
+df["dissatisfied"] = await df.jev.noul(
+    "Is this customer dissatisfied?",
+    state=["title", "review"],
+)
+
+topics = await df.jev.choice(
+    "What is the main issue?",
+    choices=["billing", "bug", "other"],
+    state="review",
+)
+
+grades = await df.jev.score(
+    "How positive is this review?",
+    levels=["Negative", "Neutral", "Positive"],
+    state="review",
+)
+
+results = await df.jev.evaluate(
+    state=["title", "review"],
+    questions={
+        "urgent": Noul(instructions="Does the customer need help today?"),
+        "topic": Choice(
+            instructions="What is the main issue?",
+            criteria={"billing": "Charges and refunds", "bug": "Broken behavior", "other": None},
+        ),
+    },
+)
+```
+
+| Method | Result columns |
+| --- | --- |
+| `noul` | Series named `probability`, the probability of yes |
+| `choice` | `label`, `confidence`, `p__billing`, `p__bug`, … |
+| `score` | `level`, `label`, `score`, `confidence`, `p__0`, `p__1`, … |
+| `evaluate` | Fields prefixed by question name, e.g. `urgent__probability`, `topic__p__billing` |
+
+`score` is the expected **zero-based** level, not a probability: with five levels it
+ranges from 0 to 4. `level`/`label` identify the highest-probability level, with ties
+resolved by level order. Structured SDK level descriptions appear as JSON text in
+`label`. Confidence comes from the SDK; it is separate from the selected option's
+probability. No result is thresholded or silently renormalized.
+
+Question and criterion order determine column order. Row order and pandas indexes,
+including duplicates and MultiIndexes, are preserved. The input is never mutated.
+
+### Output layout
+
+`choice`, `score`, and `evaluate` accept `output="columns"` (the default) or
+`output="struct"`. Both return a DataFrame with one row per input row.
+The struct layout has a single column named `result`: dictionaries in pandas
+(`object` dtype), or a native `Struct` in Polars. Its fields have exactly the same
+names, order, and values as the separate columns, including all probabilities.
+`evaluate` keeps question prefixes inside the struct too.
+
+```python
+packed = await df.jev.evaluate(
+    state="review",
+    questions={
+        "dissatisfied": Noul(instructions="Is this customer dissatisfied?"),
+        "urgent": Noul(instructions="Does the customer need help today?"),
+    },
+    output="struct",
+)
+df["decisions"] = packed["result"]
+# Each successful cell: {"dissatisfied__probability": 0.9, "urgent__probability": 0.8}
+# Illustrative probabilities; actual values come from Jev.
+```
+
+Failed or skipped rows have a missing `result` cell (`None` in pandas, null in
+Polars). Empty results retain their output dtype, including the full Polars struct
+schema. Layout affects only presentation: switching it makes no extra requests
+when you reuse a cache. `noul` always returns its single probability Series.
+
+## How requests and results map to rows
+
+The engine sends **one input row per request**, with up to 16 row requests in flight
+by default (`max_concurrency`). With `evaluate()`, every question about that row
+shares the same context and request. Different rows are evaluated independently.
+
+For example, 100 rows with three questions produce 100 initial requests and 100
+result rows, with answers in separate columns or one structured column. Retries can add
+requests; skipped or cached rows need none. This does not expand one input row
+into multiple generated records. The demo evaluates dissatisfaction, urgency,
+and topic together for each review.
+
+## Row selection and context
+
+Select rows with the dataframe library before evaluation:
+
+```python
+subset = await df.iloc[:10].jev.noul("Is this urgent?", state="review")
+
+custom = await df.jev.noul(
+    "Is this urgent?",
+    state=lambda row: {"text": f"{row['title']}: {row['review']}"},
+)
+```
+
+`state="review"` sends `{"review": value}`; a list sends those named columns.
+Indexes are never sent implicitly. Selected column names must be unique strings;
+unrelated duplicate columns are allowed. A synchronous context callable receives
+a detached mapping of all columns and returns text, an object, or an array. It
+runs once per row before cache lookup. Polars temporal values in these mappings
+are ISO strings to retain nanosecond precision.
+
+Missing scalars become JSON null; lists and objects are normalized recursively.
+Dates/times become ISO text. Unsupported objects and infinities raise a row-aware
+context error. Supply a callable to convert custom values. Context errors always
+raise, even under `errors="coerce"`.
+
+## Eager Polars
+
+```python
+import polars as pl
+import jevframe.polars
+
+df = pl.DataFrame({"review": ["Charged twice", "Works perfectly"]})
+probabilities = await df.jev.noul("Is this customer dissatisfied?", state="review")
+df = df.with_columns(probabilities.alias("dissatisfied"))
+topics = await df.filter(pl.col("dissatisfied") > 0.5).jev.choice(
+    "What is the issue?",
+    choices=["billing", "bug", "other"],
+    state="review",
+)
+```
+
+The API and columns match pandas; outputs are native `pl.Series`/`pl.DataFrame`.
+Polars uses nulls for missing results; pandas uses NaN for floating outputs and
+native nullable string/integer columns. Empty outputs retain their schemas.
+LazyFrame expressions are outside v0.
+
+## Controls, errors, and caching
+
+Every method accepts these keyword arguments:
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `client` | `None` | Reuse an official `AsyncTypeSafeClient`; caller owns its lifetime |
+| `model` | `None` | Inherit SDK client/environment default (`jev-latest` otherwise) |
+| `max_concurrency` | `16` | Maximum simultaneous row evaluations, including retries |
+| `cache` | `None` | Opt in with a reusable `MemoryCache` |
+| `progress` | `False` | `True` for tqdm, or a synchronous `Progress` callback |
+| `errors` | `"raise"` | `"coerce"` returns missing results and an `EvaluationWarning` |
+| `nulls` | `"include"` | `"skip"` skips rows with any null context; `"raise"` rejects them |
+
+Null policy applies **after** constructing context, including nested nulls. A row
+failure makes every question result for that row missing. `EvaluationError.position`
+and `.cause`, or `EvaluationWarning.failures` (`RowFailure.position`/`.cause`), identify
+failures without confusing duplicate index labels. Positions refer to the evaluated
+frame, starting at zero. Inspect warnings with `warnings.catch_warnings(record=True)`.
+Progress snapshots expose `completed`, `total`, `failed`, `skipped`, and `cache_hits`.
+Callback exceptions and cancellation propagate, and outstanding workers are drained.
+
+All questions for a row share one request. SDK retries handle transient failures and
+backoff (two retries by default); configure its policy and timeouts directly:
+
+```python
+from jevframe import MemoryCache
+from typesafe_sdk import AsyncTypeSafeClient, RetryPolicy
+
+cache = MemoryCache(max_entries=10_000)
+async with AsyncTypeSafeClient(timeout=30, retry=RetryPolicy(max_retries=3)) as client:
+    result = await df.jev.noul(
+        "Is this urgent?",
+        state="review",
+        client=client,
+        max_concurrency=8,
+        cache=cache,
+        progress=True,
+    )
+```
+
+The memory cache stores only successful, validated complete responses, including
+all probabilities. Identical in-flight rows within one evaluation share a request.
+Questions, criteria order, context, model, and client/configuration identity affect
+cache keys; indexes do not. Supplied clients have separate cache namespaces. Default
+clients reuse entries across calls when their environment configuration matches.
+There is no disk cache. Model aliases can change: use a pinned model for reproducible
+work and `cache.clear()` when fresh results are needed.
+
+No API call runs merely by importing the library. Evaluation sends the chosen
+context to TypeSafe. Late context errors can occur after other rows have completed;
+completed requests cannot be undone. Credentials are read from the environment or
+the SDK client; the library does not discover or load dotenv files.
+
+## marimo example and development
+
+From a checkout:
+
+```sh
+# For library development only: uv sync --extra pandas (or --extra polars)
+uv sync --extra examples
+uv run marimo edit examples/reviews.py
+```
+
+Edit the three questions, choose an output layout, and click **Evaluate reviews**
+to see the results and probability histograms. The eight synthetic reviews need eight initial
+requests, each containing all three questions; repeated evaluations reuse the cache.
+The example makes no requests until the button is clicked and a key is configured.
+
+The badge opens the GitHub notebook preview. Fork it into your molab workspace to
+add your own secret and run it on a server. The notebook includes inline dependency
+metadata that installs `jevframe[pandas]==0.1.0` from PyPI. The badge requires the
+notebook to be available on this repository's `main` branch.
+
+For development checks, install all extras:
+
+```sh
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run marimo check --strict examples/reviews.py
+uv build
+```
+
+Tests use the official SDK with mocked HTTP transport; no API key or live calls
+are required. v0 focuses on row-wise decisions, with no chat interface, automatic
+analysis, generated code, custom dtypes, Excel integration, or provider framework.

jevframe-0.1.0/README.md

@@ -0,0 +1,261 @@
+# jevframe
+
+[![Open in molab](https://marimo.io/molab-shield.svg)](https://molab.marimo.io/github/ktaletsk/jevframe/blob/main/examples/reviews.py)
+
+Ask the same semantic questions about every row of a dataframe using
+[TypeSafe Jev](https://docs.typesafe.ai/). Get ordinary pandas or Polars results,
+with bounded async inference and complete probability distributions.
+
+## Install
+
+```sh
+uv add 'jevframe[pandas]==0.1.0'     # in your uv project
+# Or: uv add 'jevframe[polars]==0.1.0' / 'jevframe[pandas,polars]==0.1.0'
+export TYPESAFE_API_KEY='your-key'
+```
+
+Python 3.10+; the official `typesafe-sdk>=0.7,<0.8` handles inference. Dataframe
+dependencies are optional. Importing an integration registers its `.jev` accessor.
+
+On **molab**, open the notebook's **Secrets** sidebar panel and add
+`TYPESAFE_API_KEY` with your key as its value. molab loads it automatically and
+persists it between sessions; `.env` secrets are excluded from forks.
+[Molab's secrets documentation](https://marimo.io/pages/molab/storage#secrets-stay-with-your-notebook).
+Then click **Evaluate reviews** in the demo. You do not need to put the key in a code cell.
+
+## pandas
+
+These examples use notebook top-level `await`. In a script, put them inside an
+`async def main()` and call `asyncio.run(main())`.
+
+```python
+import pandas as pd
+import jevframe.pandas
+from typesafe_sdk import Choice, Noul
+
+df = pd.DataFrame(
+    {
+        "title": ["Charged twice", "Great update"],
+        "review": ["Please refund the duplicate charge today.", "Everything works well!"],
+    }
+)
+
+df["dissatisfied"] = await df.jev.noul(
+    "Is this customer dissatisfied?",
+    state=["title", "review"],
+)
+
+topics = await df.jev.choice(
+    "What is the main issue?",
+    choices=["billing", "bug", "other"],
+    state="review",
+)
+
+grades = await df.jev.score(
+    "How positive is this review?",
+    levels=["Negative", "Neutral", "Positive"],
+    state="review",
+)
+
+results = await df.jev.evaluate(
+    state=["title", "review"],
+    questions={
+        "urgent": Noul(instructions="Does the customer need help today?"),
+        "topic": Choice(
+            instructions="What is the main issue?",
+            criteria={"billing": "Charges and refunds", "bug": "Broken behavior", "other": None},
+        ),
+    },
+)
+```
+
+| Method | Result columns |
+| --- | --- |
+| `noul` | Series named `probability`, the probability of yes |
+| `choice` | `label`, `confidence`, `p__billing`, `p__bug`, … |
+| `score` | `level`, `label`, `score`, `confidence`, `p__0`, `p__1`, … |
+| `evaluate` | Fields prefixed by question name, e.g. `urgent__probability`, `topic__p__billing` |
+
+`score` is the expected **zero-based** level, not a probability: with five levels it
+ranges from 0 to 4. `level`/`label` identify the highest-probability level, with ties
+resolved by level order. Structured SDK level descriptions appear as JSON text in
+`label`. Confidence comes from the SDK; it is separate from the selected option's
+probability. No result is thresholded or silently renormalized.
+
+Question and criterion order determine column order. Row order and pandas indexes,
+including duplicates and MultiIndexes, are preserved. The input is never mutated.
+
+### Output layout
+
+`choice`, `score`, and `evaluate` accept `output="columns"` (the default) or
+`output="struct"`. Both return a DataFrame with one row per input row.
+The struct layout has a single column named `result`: dictionaries in pandas
+(`object` dtype), or a native `Struct` in Polars. Its fields have exactly the same
+names, order, and values as the separate columns, including all probabilities.
+`evaluate` keeps question prefixes inside the struct too.
+
+```python
+packed = await df.jev.evaluate(
+    state="review",
+    questions={
+        "dissatisfied": Noul(instructions="Is this customer dissatisfied?"),
+        "urgent": Noul(instructions="Does the customer need help today?"),
+    },
+    output="struct",
+)
+df["decisions"] = packed["result"]
+# Each successful cell: {"dissatisfied__probability": 0.9, "urgent__probability": 0.8}
+# Illustrative probabilities; actual values come from Jev.
+```
+
+Failed or skipped rows have a missing `result` cell (`None` in pandas, null in
+Polars). Empty results retain their output dtype, including the full Polars struct
+schema. Layout affects only presentation: switching it makes no extra requests
+when you reuse a cache. `noul` always returns its single probability Series.
+
+## How requests and results map to rows
+
+The engine sends **one input row per request**, with up to 16 row requests in flight
+by default (`max_concurrency`). With `evaluate()`, every question about that row
+shares the same context and request. Different rows are evaluated independently.
+
+For example, 100 rows with three questions produce 100 initial requests and 100
+result rows, with answers in separate columns or one structured column. Retries can add
+requests; skipped or cached rows need none. This does not expand one input row
+into multiple generated records. The demo evaluates dissatisfaction, urgency,
+and topic together for each review.
+
+## Row selection and context
+
+Select rows with the dataframe library before evaluation:
+
+```python
+subset = await df.iloc[:10].jev.noul("Is this urgent?", state="review")
+
+custom = await df.jev.noul(
+    "Is this urgent?",
+    state=lambda row: {"text": f"{row['title']}: {row['review']}"},
+)
+```
+
+`state="review"` sends `{"review": value}`; a list sends those named columns.
+Indexes are never sent implicitly. Selected column names must be unique strings;
+unrelated duplicate columns are allowed. A synchronous context callable receives
+a detached mapping of all columns and returns text, an object, or an array. It
+runs once per row before cache lookup. Polars temporal values in these mappings
+are ISO strings to retain nanosecond precision.
+
+Missing scalars become JSON null; lists and objects are normalized recursively.
+Dates/times become ISO text. Unsupported objects and infinities raise a row-aware
+context error. Supply a callable to convert custom values. Context errors always
+raise, even under `errors="coerce"`.
+
+## Eager Polars
+
+```python
+import polars as pl
+import jevframe.polars
+
+df = pl.DataFrame({"review": ["Charged twice", "Works perfectly"]})
+probabilities = await df.jev.noul("Is this customer dissatisfied?", state="review")
+df = df.with_columns(probabilities.alias("dissatisfied"))
+topics = await df.filter(pl.col("dissatisfied") > 0.5).jev.choice(
+    "What is the issue?",
+    choices=["billing", "bug", "other"],
+    state="review",
+)
+```
+
+The API and columns match pandas; outputs are native `pl.Series`/`pl.DataFrame`.
+Polars uses nulls for missing results; pandas uses NaN for floating outputs and
+native nullable string/integer columns. Empty outputs retain their schemas.
+LazyFrame expressions are outside v0.
+
+## Controls, errors, and caching
+
+Every method accepts these keyword arguments:
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `client` | `None` | Reuse an official `AsyncTypeSafeClient`; caller owns its lifetime |
+| `model` | `None` | Inherit SDK client/environment default (`jev-latest` otherwise) |
+| `max_concurrency` | `16` | Maximum simultaneous row evaluations, including retries |
+| `cache` | `None` | Opt in with a reusable `MemoryCache` |
+| `progress` | `False` | `True` for tqdm, or a synchronous `Progress` callback |
+| `errors` | `"raise"` | `"coerce"` returns missing results and an `EvaluationWarning` |
+| `nulls` | `"include"` | `"skip"` skips rows with any null context; `"raise"` rejects them |
+
+Null policy applies **after** constructing context, including nested nulls. A row
+failure makes every question result for that row missing. `EvaluationError.position`
+and `.cause`, or `EvaluationWarning.failures` (`RowFailure.position`/`.cause`), identify
+failures without confusing duplicate index labels. Positions refer to the evaluated
+frame, starting at zero. Inspect warnings with `warnings.catch_warnings(record=True)`.
+Progress snapshots expose `completed`, `total`, `failed`, `skipped`, and `cache_hits`.
+Callback exceptions and cancellation propagate, and outstanding workers are drained.
+
+All questions for a row share one request. SDK retries handle transient failures and
+backoff (two retries by default); configure its policy and timeouts directly:
+
+```python
+from jevframe import MemoryCache
+from typesafe_sdk import AsyncTypeSafeClient, RetryPolicy
+
+cache = MemoryCache(max_entries=10_000)
+async with AsyncTypeSafeClient(timeout=30, retry=RetryPolicy(max_retries=3)) as client:
+    result = await df.jev.noul(
+        "Is this urgent?",
+        state="review",
+        client=client,
+        max_concurrency=8,
+        cache=cache,
+        progress=True,
+    )
+```
+
+The memory cache stores only successful, validated complete responses, including
+all probabilities. Identical in-flight rows within one evaluation share a request.
+Questions, criteria order, context, model, and client/configuration identity affect
+cache keys; indexes do not. Supplied clients have separate cache namespaces. Default
+clients reuse entries across calls when their environment configuration matches.
+There is no disk cache. Model aliases can change: use a pinned model for reproducible
+work and `cache.clear()` when fresh results are needed.
+
+No API call runs merely by importing the library. Evaluation sends the chosen
+context to TypeSafe. Late context errors can occur after other rows have completed;
+completed requests cannot be undone. Credentials are read from the environment or
+the SDK client; the library does not discover or load dotenv files.
+
+## marimo example and development
+
+From a checkout:
+
+```sh
+# For library development only: uv sync --extra pandas (or --extra polars)
+uv sync --extra examples
+uv run marimo edit examples/reviews.py
+```
+
+Edit the three questions, choose an output layout, and click **Evaluate reviews**
+to see the results and probability histograms. The eight synthetic reviews need eight initial
+requests, each containing all three questions; repeated evaluations reuse the cache.
+The example makes no requests until the button is clicked and a key is configured.
+
+The badge opens the GitHub notebook preview. Fork it into your molab workspace to
+add your own secret and run it on a server. The notebook includes inline dependency
+metadata that installs `jevframe[pandas]==0.1.0` from PyPI. The badge requires the
+notebook to be available on this repository's `main` branch.
+
+For development checks, install all extras:
+
+```sh
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run marimo check --strict examples/reviews.py
+uv build
+```
+
+Tests use the official SDK with mocked HTTP transport; no API key or live calls
+are required. v0 focuses on row-wise decisions, with no chat interface, automatic
+analysis, generated code, custom dtypes, Excel integration, or provider framework.