ergoda 0.1.0__tar.gz

ergoda-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Deps / build
+node_modules/
+dist/
+build/
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+
+# Data / scratch
+*.log
+tmp/
+scratch/
+/traces/
+
+# Local databases
+*.db
+
+# Replay cache: raw model responses. On a real customer trace this holds
+# customer payloads — it must never be committed.
+.ergoda-cache/
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+
+# DTap-Bench working set: 50 MB, rebuilt deterministically by experiments/dtap_index.py
+experiments/dtap_index.json
+# Third-party dataset cache (CC-BY-4.0), rebuilt by experiments/compounding.py
+experiments/trajectories.json
+
+# Coverage artefacts (the CI gate reports; nothing here is worth committing)
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+experiments/taubench_dry.jsonl
+
+# Vercel: the linked project, and the role URLs `hosted roles` writes (secrets).
+.vercel/
+.ergoda-roles.env

ergoda-0.1.0/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Maffen Oy
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+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.

ergoda-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: ergoda
+Version: 0.1.0
+Summary: Measure which steps of your agent can run on a cheaper model, and keep measuring
+Author: Ergoda
+License-Expression: FSL-1.1-ALv2
+License-File: LICENSE.md
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.111; extra == 'all'
+Requires-Dist: litellm<2,>=1.40; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Requires-Dist: python-multipart>=0.0.9; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: hosted
+Requires-Dist: psycopg[binary]>=3.1; extra == 'hosted'
+Requires-Dist: sentry-sdk>=2.0; extra == 'hosted'
+Provides-Extra: litellm
+Requires-Dist: litellm<2,>=1.40; extra == 'litellm'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111; extra == 'server'
+Requires-Dist: python-multipart>=0.0.9; extra == 'server'
+Requires-Dist: uvicorn>=0.30; extra == 'server'
+Description-Content-Type: text/markdown
+
+# ergoda
+
+Measures which steps of your agent can run on a cheaper model, and keeps
+measuring once they do. Your code keeps calling your own provider with your
+own key. Ergoda decides which model a step uses, and anything it cannot
+decide goes to the model you would have called anyway.
+
+```sh
+pip install ergoda
+ergoda onboard --sample    # a first report on bundled sample data, offline
+```
+
+The ten-minute path is the [quickstart](https://ergoda.com/docs/quickstart/);
+every term is defined in [concepts](https://ergoda.com/docs/concepts/).
+
+## Start: measure before anything moves
+
+```sh
+ergoda init --frontier anthropic/claude-opus-5 --step resolve_ticket
+```
+
+This writes a `routes.yaml` that routes nothing: every step keeps serving
+the model your code already asks for. It prints the two lines to paste:
+
+```python
+from ergoda.sdk import Client
+
+ergoda = Client.from_env()
+create = ergoda.wrap({"anthropic": client.messages.create}, step="resolve_ticket")
+
+# unchanged from here: same arguments, same response object
+response = create(model="claude-opus-5", max_tokens=1024, messages=msgs, tools=TOOLS)
+```
+
+Add `--control-plane https://api.ergoda.com --email you@company.com` to get
+a site key, so the metrics reach a control plane where they accumulate, and a
+dashboard at https://app.ergoda.com/ (sign in with the email address you
+signed up with; until email sign-in is switched on, the page links a sign-in
+with the site key). Only derived
+metrics are sent (hashes, counts, token totals). Prompts and responses stay in
+your process. The control plane is a hosted service: it is not in this
+package, and running your own is not offered.
+
+## Then: find what can move
+
+No trace export yet? Wrap your create call as
+`record(client.messages.create)` (`from ergoda import record`) and it writes
+one to `traces.jsonl` on your own disk as your agent runs. Langfuse, LangSmith
+and OpenTelemetry exports are read as they are.
+
+```sh
+ergoda onboard traces.jsonl --step resolve_ticket \
+  --serve anthropic/claude-haiku-4-5 --escalate-to anthropic/claude-opus-5
+ergoda analyse traces.jsonl --model anthropic/claude-haiku-4-5 --html report.html
+```
+
+`onboard` checks that the export can be replayed, lists the tools whose
+effects can be undone, and prints the policy it would write. It writes
+nothing until a named person approves: add `--approved-by "Your Name"`.
+`analyse` replays your traces against the cheaper model with your own key and
+reports agreement per step with an interval. Without that key it stops and
+names the variable; a replay the provider refuses is counted as a failure,
+never as a disagreement.
+
+## What it will and will not do
+
+- **Doubt goes to the expensive model.** An unknown step, an unreachable
+  control plane, a changed prompt or a refused proposal all serve your own
+  frontier model.
+- **A route to a cheaper model starts with a person's name on the record.**
+  After that, autopilot may loosen an approved route's checks where your own
+  traffic shows at most a 2% added failure rate at 95% confidence. That
+  limit is a published default, not one a person on your team accepted, so
+  its moves are recorded as `ergoda:default`. You can switch it off for your
+  site on the dashboard's Switch autopilot off page, or with
+  `POST /v1/sites/SITE/autopilot` and `{"by": "your name", "enabled": false}`;
+  every move toward the cheaper model then waits for a named person. Moves it
+  already made stay until you revert them or an escalation takes them back;
+  only a route with no traffic for 90 days goes back on its own. Setting a route's
+  `enabled: false` sends that step back to your frontier model.
+- **Routing is not meant to cost more than not routing.** In the Python SDK,
+  a route whose spend passes what the frontier model alone would have cost is
+  pinned back to the frontier. The TypeScript SDK and the proxy do not
+  enforce this yet.
+- **The numbers are estimates with intervals.** Agreement is measured on your
+  traffic and reported with its bound. Parity is about task completion; refusal
+  behaviour is not measured.
+
+## Latency
+
+The decision is in-process, with no network hop on the request path, and
+takes about a millisecond. A step the cheaper model gets wrong is redone by
+the frontier model, so that step makes two calls in a row. Shipped
+with your deployment, `routes.yaml` is in force from the first call, and the
+control plane is consulted behind it. In a Lambda or Cloud Run handler, build
+the client at module scope and wrap the body in `with ergoda.request():` so
+queued metrics are delivered before the process is frozen.
+
+Python 3.11+. OpenAI, Anthropic, Gemini and Bedrock request and tool-call
+shapes are read natively. Other providers go through the optional `litellm`
+extra. `pip install 'ergoda[server]'` adds what the proxy needs, for agents
+that reach their provider through a base URL (`ergoda dataplane serve`).
+
+Documentation: https://ergoda.com/docs/quickstart/
+
+Licence: [FSL-1.1-ALv2](https://fsl.software/), source-available. Use it for
+anything, in production and commercially, except a product or service that
+competes with Ergoda; each version becomes Apache 2.0 two years after it is
+published.

ergoda-0.1.0/docs/pypi.md

@@ -0,0 +1,109 @@
+# ergoda
+
+Measures which steps of your agent can run on a cheaper model, and keeps
+measuring once they do. Your code keeps calling your own provider with your
+own key. Ergoda decides which model a step uses, and anything it cannot
+decide goes to the model you would have called anyway.
+
+```sh
+pip install ergoda
+ergoda onboard --sample    # a first report on bundled sample data, offline
+```
+
+The ten-minute path is the [quickstart](https://ergoda.com/docs/quickstart/);
+every term is defined in [concepts](https://ergoda.com/docs/concepts/).
+
+## Start: measure before anything moves
+
+```sh
+ergoda init --frontier anthropic/claude-opus-5 --step resolve_ticket
+```
+
+This writes a `routes.yaml` that routes nothing: every step keeps serving
+the model your code already asks for. It prints the two lines to paste:
+
+```python
+from ergoda.sdk import Client
+
+ergoda = Client.from_env()
+create = ergoda.wrap({"anthropic": client.messages.create}, step="resolve_ticket")
+
+# unchanged from here: same arguments, same response object
+response = create(model="claude-opus-5", max_tokens=1024, messages=msgs, tools=TOOLS)
+```
+
+Add `--control-plane https://api.ergoda.com --email you@company.com` to get
+a site key, so the metrics reach a control plane where they accumulate, and a
+dashboard at https://app.ergoda.com/ (sign in with the email address you
+signed up with; until email sign-in is switched on, the page links a sign-in
+with the site key). Only derived
+metrics are sent (hashes, counts, token totals). Prompts and responses stay in
+your process. The control plane is a hosted service: it is not in this
+package, and running your own is not offered.
+
+## Then: find what can move
+
+No trace export yet? Wrap your create call as
+`record(client.messages.create)` (`from ergoda import record`) and it writes
+one to `traces.jsonl` on your own disk as your agent runs. Langfuse, LangSmith
+and OpenTelemetry exports are read as they are.
+
+```sh
+ergoda onboard traces.jsonl --step resolve_ticket \
+  --serve anthropic/claude-haiku-4-5 --escalate-to anthropic/claude-opus-5
+ergoda analyse traces.jsonl --model anthropic/claude-haiku-4-5 --html report.html
+```
+
+`onboard` checks that the export can be replayed, lists the tools whose
+effects can be undone, and prints the policy it would write. It writes
+nothing until a named person approves: add `--approved-by "Your Name"`.
+`analyse` replays your traces against the cheaper model with your own key and
+reports agreement per step with an interval. Without that key it stops and
+names the variable; a replay the provider refuses is counted as a failure,
+never as a disagreement.
+
+## What it will and will not do
+
+- **Doubt goes to the expensive model.** An unknown step, an unreachable
+  control plane, a changed prompt or a refused proposal all serve your own
+  frontier model.
+- **A route to a cheaper model starts with a person's name on the record.**
+  After that, autopilot may loosen an approved route's checks where your own
+  traffic shows at most a 2% added failure rate at 95% confidence. That
+  limit is a published default, not one a person on your team accepted, so
+  its moves are recorded as `ergoda:default`. You can switch it off for your
+  site on the dashboard's Switch autopilot off page, or with
+  `POST /v1/sites/SITE/autopilot` and `{"by": "your name", "enabled": false}`;
+  every move toward the cheaper model then waits for a named person. Moves it
+  already made stay until you revert them or an escalation takes them back;
+  only a route with no traffic for 90 days goes back on its own. Setting a route's
+  `enabled: false` sends that step back to your frontier model.
+- **Routing is not meant to cost more than not routing.** In the Python SDK,
+  a route whose spend passes what the frontier model alone would have cost is
+  pinned back to the frontier. The TypeScript SDK and the proxy do not
+  enforce this yet.
+- **The numbers are estimates with intervals.** Agreement is measured on your
+  traffic and reported with its bound. Parity is about task completion; refusal
+  behaviour is not measured.
+
+## Latency
+
+The decision is in-process, with no network hop on the request path, and
+takes about a millisecond. A step the cheaper model gets wrong is redone by
+the frontier model, so that step makes two calls in a row. Shipped
+with your deployment, `routes.yaml` is in force from the first call, and the
+control plane is consulted behind it. In a Lambda or Cloud Run handler, build
+the client at module scope and wrap the body in `with ergoda.request():` so
+queued metrics are delivered before the process is frozen.
+
+Python 3.11+. OpenAI, Anthropic, Gemini and Bedrock request and tool-call
+shapes are read natively. Other providers go through the optional `litellm`
+extra. `pip install 'ergoda[server]'` adds what the proxy needs, for agents
+that reach their provider through a base URL (`ergoda dataplane serve`).
+
+Documentation: https://ergoda.com/docs/quickstart/
+
+Licence: [FSL-1.1-ALv2](https://fsl.software/), source-available. Use it for
+anything, in production and commercially, except a product or service that
+competes with Ergoda; each version becomes Apache 2.0 two years after it is
+published.

ergoda-0.1.0/hatch_build.py

@@ -0,0 +1,184 @@
+"""Which build of ``ergoda`` this is: the public one, or the full one.
+
+The public wheel and sdist, the ones bound for PyPI, carry the SDK, the
+analyser and the data plane. They leave out ``PRIVATE``: the control plane
+(the metered, hosted product: billing, autopilot, the licensing statistics),
+the synthetic worlds and the harness that runs them, the benchmark fixtures,
+the hosted no-signup web tool, and the Codex CLI transport, which drives a
+ChatGPT subscription and is research tooling. Publishing to an index cannot
+be undone, so the exclusion is the DEFAULT: it is written in
+``pyproject.toml`` as a static ``exclude`` and holds even if this hook never
+ran.
+
+``ERGODA_WHEEL=full`` builds everything, as the hosted deploys and the
+control-plane image need. That name is a contract with those builds; do not
+rename it. The full build adds ``PRIVATE`` back with ``force_include``, which
+is the only way hatchling lets a hook add files to a target; the public
+build checks that the static exclusion still names every path here, so the
+two lists cannot drift apart without a build failing.
+
+The full build is also unpublishable by construction: its version carries
+the local segment ``+full`` (``0.1.0+full``), which PyPI refuses to accept,
+so a shell that still has ``ERGODA_WHEEL=full`` set cannot publish the
+control plane by accident, and its files are named differently from the
+public ones. ``scripts/check_dist.py`` reads a ``dist/`` directory back
+before a publish and fails on either (``docs/usage.md``, "Development").
+That is why the version is ``dynamic`` in ``pyproject.toml``: this file's
+metadata hook sets it, from ``__version__`` in ``src/ergoda/__init__.py``.
+
+``force_include`` bypasses hatch's own file selection, so the full build
+adds the private paths back file by file (``_selected``), and only files an
+ALLOWLIST names (``PRIVATE_FILES``: the modules and the licence). It used to
+take every file ``.gitignore`` did not name, which kept a ``.ergoda-roles.env``
+with an owner password in it out of the wheel only where ``.gitignore`` was
+present -- and the Vercel CLI never uploads ``.gitignore`` (it is on its own
+built-in ignore list, ahead of ``.vercelignore``), so on ``vercel deploy``
+every ``.env``, ``*.pem`` and log under a private directory went into the
+function. A file type the private directories need is added to
+``PRIVATE_FILES`` on purpose; ``tests/test_packaging.py`` fails on a tracked
+file there that the list does not name.
+
+Editable installs (``uv sync``, ``pip install -e``) put ``src/`` on the path
+and are never filtered: a development checkout always has everything.
+
+This file ships in the sdist, because a wheel built from the sdist runs it.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import pathspec
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+ENV = "ERGODA_WHEEL"
+FULL = "full"
+# Accepted spellings of "the public build", so a typo such as `Full` fails
+# instead of quietly building the public wheel for a deploy that needs the
+# control plane.
+PUBLIC = ("", "public")
+
+# Project-root-relative. A directory drops everything under it.
+PRIVATE = (
+    "src/ergoda/controlplane",
+    "src/ergoda/synth",
+    "src/ergoda/harness",
+    "src/ergoda/bench",
+    "src/ergoda/web",
+    "src/ergoda/transports/codex.py",
+)
+
+
+# What the full build takes from under ``PRIVATE``, by file name (fnmatch):
+# every tracked file there is one of these. Hidden files and directories are
+# never taken, whatever their name.
+PRIVATE_FILES = ("*.py", "LICENSE*")
+
+
+def shipped(relative: str) -> bool:
+    """Whether the full build takes the private file at ``relative``."""
+    parts = relative.split("/")
+    return not any(part.startswith(".") for part in parts) and any(
+        fnmatch.fnmatchcase(parts[-1], pattern) for pattern in PRIVATE_FILES
+    )
+
+
+# The local version segment of the full build. PyPI rejects any version with
+# one, which is the point: see the module docstring.
+LOCAL = "+full"
+VERSION_FILE = "src/ergoda/__init__.py"
+
+
+def mode() -> str:
+    """``full`` or ``public``, from the environment; anything else raises."""
+    raw = os.environ.get(ENV, "").strip()
+    if raw == FULL:
+        return FULL
+    if raw in PUBLIC:
+        return "public"
+    raise ValueError(f"{ENV}={raw!r}: set it to {FULL!r} for the full build, or leave it unset")
+
+
+def package_version(root: str | Path) -> str:
+    """``__version__`` from ``VERSION_FILE``, with ``LOCAL`` appended in the
+    full build."""
+    text = (Path(root) / VERSION_FILE).read_text(encoding="utf-8")
+    found = re.search(r'^__version__ = "([^"]+)"$', text, re.M)
+    if found is None:
+        raise ValueError(f"{VERSION_FILE} has no __version__ line")
+    return found.group(1) + (LOCAL if mode() == FULL else "")
+
+
+class ErgodaMetadataHook(MetadataHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def update(self, metadata: dict[str, Any]) -> None:
+        metadata["version"] = package_version(self.root)
+
+
+class ErgodaBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if version == "editable":
+            return
+        root = Path(self.root)
+        if mode() == FULL:
+            missing = [path for path in PRIVATE if not (root / path).exists()]
+            if missing:
+                raise FileNotFoundError(
+                    f"{ENV}={FULL} needs {', '.join(missing)}, which this source tree does "
+                    "not have: it is a public sdist. Build the full package from the repository."
+                )
+            for path in self._selected(root):
+                build_data["force_include"][str(root / path)] = path
+            return
+        # The public build: the static exclusion must cover every private path.
+        leaked = [
+            path
+            for path in PRIVATE
+            if not self.build_config.path_is_excluded(
+                path if path.endswith(".py") else f"{path}/__init__.py"
+            )
+        ]
+        if leaked:
+            raise ValueError(
+                f"pyproject.toml's [tool.hatch.build] exclude no longer names {leaked}; "
+                "the public build would publish them"
+            )
+
+    def _selected(self, root: Path) -> Iterator[str]:
+        """Every file under ``PRIVATE`` the allowlist names (``shipped``).
+
+        What ``.gitignore`` names is left out as well where the file is
+        present, and hatch's global excludes (compiled files) always; neither
+        is what keeps a secret out, since the first is absent from a Vercel
+        upload. Pruned by directory, so an ignored or hidden one is not
+        walked."""
+        config = self.build_config
+        patterns = list(config.default_global_exclude())
+        if not config.ignore_vcs:
+            patterns += config.load_vcs_exclusion_patterns()
+        ignored = pathspec.GitIgnoreSpec.from_lines(patterns)
+        for path in PRIVATE:
+            if (root / path).is_file():
+                if shipped(path) and not ignored.match_file(path):
+                    yield path
+                continue
+            for directory, subdirectories, files in os.walk(root / path):
+                relative = Path(directory).relative_to(root).as_posix()
+                subdirectories[:] = sorted(
+                    d
+                    for d in subdirectories
+                    if not d.startswith(".") and not ignored.match_file(f"{relative}/{d}/")
+                )
+                for name in sorted(files):
+                    file = f"{relative}/{name}"
+                    if shipped(file) and not ignored.match_file(file):
+                        yield file