myli 0.1.2__tar.gz

myli-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build and release
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out the release tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.28"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install Python
+        run: uv python install 3.14
+
+      - name: Install the project
+        run: uv sync --locked --python 3.14
+
+      - name: Verify tag matches package version
+        run: |
+          package_version="$(uv run python -c 'import myli; print(myli.__version__)')"
+          if [[ "${GITHUB_REF_NAME}" != "v${package_version}" ]]; then
+            echo "Release tag ${GITHUB_REF_NAME} does not match package version ${package_version}." >&2
+            exit 1
+          fi
+
+      - name: Check formatting
+        run: uv run ruff format --check src tests
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run python -m unittest discover -s tests -v
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
+            gh release upload "${GITHUB_REF_NAME}" dist/* --clobber
+          else
+            gh release create "${GITHUB_REF_NAME}" dist/* \
+              --generate-notes \
+              --title "Myli ${GITHUB_REF_NAME}" \
+              --verify-tag
+          fi
+
+  pypi:
+    name: Publish to PyPI
+    needs: release
+    runs-on: ubuntu-24.04
+
+    environment:
+      name: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.28"
+          enable-cache: false
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        run: uv publish

myli-0.1.2/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.idea/
+.venv/
+build/
+dist/
+docs/_build/

myli-0.1.2/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/source/conf.py
+  builder: dirhtml
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

myli-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Myli contributors
+
+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.

myli-0.1.2/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: myli
+Version: 0.1.2
+Summary: A provider-neutral harness for structured visual-design agents
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,asset-search,design,vision
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.18.0
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40.0; extra == 'litellm'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# Myli
+
+Myli is a provider-neutral, pre-alpha Python harness for agents that propose
+RFC 6902 changes to application-owned JSON design documents. It never persists
+or applies the returned candidate to application state.
+
+The core is independent of Pydantic, canvas formats, rendering stacks, model
+providers, ORMs, progress transports, and persistence systems.
+
+## Run contract
+
+~~~python
+result = await myli.run(
+    request=user_request,
+    design=current_design,
+    can_edit=True,
+    capabilities={"media.transform"},
+    history=history,
+    on_event=handle_event,
+    on_step=persist_step,
+)
+~~~
+
+RunResult contains the user-facing message, optional validated candidate,
+changed flag, proposed patch, approved run-scoped assets, all tool outcomes,
+step traces, run ID, and final provider metadata. Successful and unsuccessful
+tool outcomes are also available as filtered properties.
+
+## Generic documents and injected models
+
+~~~python
+from typing import Any
+
+from myli import DesignSpec, ModelRequest, ModelResponse, Myli
+
+
+def load_untrusted_document(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("document must be an object")
+    return value
+
+
+design_spec = DesignSpec(
+    name="design",
+    schema={"type": "object"},
+    validator=load_untrusted_document,
+    serializer=lambda document: document,
+    normalizer=normalize_trusted_stored_document,
+    input_migrator=migrate_stored_document,
+)
+
+
+class ApplicationMainModel:
+    async def complete(self, request: ModelRequest) -> ModelResponse:
+        return await application_transport.complete(request)
+
+
+myli = Myli(
+    design_spec=design_spec,
+    main_model=ApplicationMainModel(),
+    vision_model=application_vision_model,
+    renderer=application_renderer,
+)
+~~~
+
+DesignSpec has deliberately separate methods for trusted stored input and
+untrusted model candidates. Candidate JSON is validated at runtime against the
+schema and must serialize back without coercion, default insertion, field
+dropping, or any other silent rewrite. Stored input may opt into migration and
+normalization before each run.
+
+MainModel and VisionModel are public protocols. Applications may inject
+different transports, endpoints, credentials, or fakes. LiteLLMMainModel and
+LiteLLMVisionModel are optional implementations:
+
+~~~bash
+python -m pip install "myli[litellm]"
+~~~
+
+The LiteLLM main implementation supports structured, JSON, and text output
+modes, rejects options that override client-owned request fields, and translates
+provider failures into Myli's stable exception hierarchy.
+
+Pydantic remains optional:
+
+~~~python
+from myli.integrations.pydantic import PydanticDesignSpec
+~~~
+
+## Tools, policies, and middleware
+
+AgentTool is domain-neutral. A tool declares a JSON input schema, capabilities,
+per-run call budget, timeout, and result-size limit, then receives a ToolContext
+with the current run ID, isolated evidence, zero-based model step, run-unique
+step and tool-batch IDs, and its zero-based position and size within that batch:
+
+~~~python
+async def execute(arguments, context):
+    ...
+~~~
+
+Myli validates arguments and results, enforces capabilities and limits, and
+records a ToolOutcome with one of succeeded, failed, rejected, timed_out, or
+deferred. Calls are sequential by default. Parallel execution requires both the
+harness option and an explicit parallel_safe declaration on every call in the
+batch. Each tool can select FailureMode.RETURN_ERROR or FailureMode.RAISE.
+
+ToolMiddleware can allow, reject, or defer work before execution and observe the
+outcome afterward. Applications can use it for approval, audit, tenancy,
+ordering, transactions, and rate limiting. The step and batch metadata lets
+middleware apply a rule exactly once per model work phase, including when a
+batch executes in parallel.
+
+CandidatePolicy runs before rendering a proposal and before returning the final
+candidate. CandidateContext includes capabilities, approved assets, and all
+run-scoped outcomes; successful_tool_outcomes is the authorization-safe subset.
+
+## Assets and visual review
+
+Named asset providers return generic Asset values with application-defined
+kinds and metadata. Myli assigns run-scoped references, detects conflicting
+provider identities, applies search budgets and result limits, and tracks
+provenance.
+
+An asset can contain a RenderedArtifact preview or an async preview_loader.
+Previews load only after discovery and explicit inspection, are cached per run,
+and are bounded by timeout, byte-size, and media-type checks. Loading failures
+are returned to the model and can be retried. Binary artifacts never appear in
+step trace dictionaries.
+
+When a renderer and vision model are configured, render_design validates the
+candidate and application policies before rendering, validates the artifact,
+and returns visual feedback as a tool result. A changed candidate cannot be
+rendered while editing is disabled, but the unchanged current design can be
+rendered diagnostically.
+
+## Events, traces, and limits
+
+Events cover the run, model, tool, and validation lifecycle. They contain run
+and step IDs, status, safe messages, elapsed time, and an optional tool name,
+but no arguments or results. Applications can map them to logs, metrics, SSE,
+WebSockets, or ignore them.
+
+StepTrace retains normalized model output, provider-exposed reasoning, tool
+calls and outcomes, validation failures, response ID, model, finish reason,
+usage, and latency. It provides to_dict() and redacted(). Async on_step and a
+configurable trace redactor make no persistence assumptions.
+
+HarnessLimits bounds model steps, retries, renders, searches, search results,
+asset inspections, patches, documents, history, artifacts, operation timeouts,
+and optionally the entire run. Every custom tool retains its own limits.
+
+## Patch and concurrency safety
+
+apply_json_patch implements add, remove, replace, move, copy, and test, including
+root operations and escaped pointers, against a deep copy. JsonPatchLimits guard
+operation count, patch bytes, pointer depth, value bytes, document bytes, invalid
+indexes, non-JSON values, non-finite numbers, child moves, and candidate
+expansion.
+
+CancelledError is never wrapped. Cancellation propagates into model, renderer,
+vision, search, preview, and custom-tool work. All counters, assets, outcomes,
+and caches live in local run state, so one Myli instance can safely serve
+concurrent requests.
+
+## Development
+
+~~~bash
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+python -m unittest discover -s tests -v
+~~~
+
+Myli is distributed under the MIT License.

myli-0.1.2/README.md

@@ -0,0 +1,175 @@
+# Myli
+
+Myli is a provider-neutral, pre-alpha Python harness for agents that propose
+RFC 6902 changes to application-owned JSON design documents. It never persists
+or applies the returned candidate to application state.
+
+The core is independent of Pydantic, canvas formats, rendering stacks, model
+providers, ORMs, progress transports, and persistence systems.
+
+## Run contract
+
+~~~python
+result = await myli.run(
+    request=user_request,
+    design=current_design,
+    can_edit=True,
+    capabilities={"media.transform"},
+    history=history,
+    on_event=handle_event,
+    on_step=persist_step,
+)
+~~~
+
+RunResult contains the user-facing message, optional validated candidate,
+changed flag, proposed patch, approved run-scoped assets, all tool outcomes,
+step traces, run ID, and final provider metadata. Successful and unsuccessful
+tool outcomes are also available as filtered properties.
+
+## Generic documents and injected models
+
+~~~python
+from typing import Any
+
+from myli import DesignSpec, ModelRequest, ModelResponse, Myli
+
+
+def load_untrusted_document(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ValueError("document must be an object")
+    return value
+
+
+design_spec = DesignSpec(
+    name="design",
+    schema={"type": "object"},
+    validator=load_untrusted_document,
+    serializer=lambda document: document,
+    normalizer=normalize_trusted_stored_document,
+    input_migrator=migrate_stored_document,
+)
+
+
+class ApplicationMainModel:
+    async def complete(self, request: ModelRequest) -> ModelResponse:
+        return await application_transport.complete(request)
+
+
+myli = Myli(
+    design_spec=design_spec,
+    main_model=ApplicationMainModel(),
+    vision_model=application_vision_model,
+    renderer=application_renderer,
+)
+~~~
+
+DesignSpec has deliberately separate methods for trusted stored input and
+untrusted model candidates. Candidate JSON is validated at runtime against the
+schema and must serialize back without coercion, default insertion, field
+dropping, or any other silent rewrite. Stored input may opt into migration and
+normalization before each run.
+
+MainModel and VisionModel are public protocols. Applications may inject
+different transports, endpoints, credentials, or fakes. LiteLLMMainModel and
+LiteLLMVisionModel are optional implementations:
+
+~~~bash
+python -m pip install "myli[litellm]"
+~~~
+
+The LiteLLM main implementation supports structured, JSON, and text output
+modes, rejects options that override client-owned request fields, and translates
+provider failures into Myli's stable exception hierarchy.
+
+Pydantic remains optional:
+
+~~~python
+from myli.integrations.pydantic import PydanticDesignSpec
+~~~
+
+## Tools, policies, and middleware
+
+AgentTool is domain-neutral. A tool declares a JSON input schema, capabilities,
+per-run call budget, timeout, and result-size limit, then receives a ToolContext
+with the current run ID, isolated evidence, zero-based model step, run-unique
+step and tool-batch IDs, and its zero-based position and size within that batch:
+
+~~~python
+async def execute(arguments, context):
+    ...
+~~~
+
+Myli validates arguments and results, enforces capabilities and limits, and
+records a ToolOutcome with one of succeeded, failed, rejected, timed_out, or
+deferred. Calls are sequential by default. Parallel execution requires both the
+harness option and an explicit parallel_safe declaration on every call in the
+batch. Each tool can select FailureMode.RETURN_ERROR or FailureMode.RAISE.
+
+ToolMiddleware can allow, reject, or defer work before execution and observe the
+outcome afterward. Applications can use it for approval, audit, tenancy,
+ordering, transactions, and rate limiting. The step and batch metadata lets
+middleware apply a rule exactly once per model work phase, including when a
+batch executes in parallel.
+
+CandidatePolicy runs before rendering a proposal and before returning the final
+candidate. CandidateContext includes capabilities, approved assets, and all
+run-scoped outcomes; successful_tool_outcomes is the authorization-safe subset.
+
+## Assets and visual review
+
+Named asset providers return generic Asset values with application-defined
+kinds and metadata. Myli assigns run-scoped references, detects conflicting
+provider identities, applies search budgets and result limits, and tracks
+provenance.
+
+An asset can contain a RenderedArtifact preview or an async preview_loader.
+Previews load only after discovery and explicit inspection, are cached per run,
+and are bounded by timeout, byte-size, and media-type checks. Loading failures
+are returned to the model and can be retried. Binary artifacts never appear in
+step trace dictionaries.
+
+When a renderer and vision model are configured, render_design validates the
+candidate and application policies before rendering, validates the artifact,
+and returns visual feedback as a tool result. A changed candidate cannot be
+rendered while editing is disabled, but the unchanged current design can be
+rendered diagnostically.
+
+## Events, traces, and limits
+
+Events cover the run, model, tool, and validation lifecycle. They contain run
+and step IDs, status, safe messages, elapsed time, and an optional tool name,
+but no arguments or results. Applications can map them to logs, metrics, SSE,
+WebSockets, or ignore them.
+
+StepTrace retains normalized model output, provider-exposed reasoning, tool
+calls and outcomes, validation failures, response ID, model, finish reason,
+usage, and latency. It provides to_dict() and redacted(). Async on_step and a
+configurable trace redactor make no persistence assumptions.
+
+HarnessLimits bounds model steps, retries, renders, searches, search results,
+asset inspections, patches, documents, history, artifacts, operation timeouts,
+and optionally the entire run. Every custom tool retains its own limits.
+
+## Patch and concurrency safety
+
+apply_json_patch implements add, remove, replace, move, copy, and test, including
+root operations and escaped pointers, against a deep copy. JsonPatchLimits guard
+operation count, patch bytes, pointer depth, value bytes, document bytes, invalid
+indexes, non-JSON values, non-finite numbers, child moves, and candidate
+expansion.
+
+CancelledError is never wrapped. Cancellation propagates into model, renderer,
+vision, search, preview, and custom-tool work. All counters, assets, outcomes,
+and caches live in local run state, so one Myli instance can safely serve
+concurrent requests.
+
+## Development
+
+~~~bash
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+python -m unittest discover -s tests -v
+~~~
+
+Myli is distributed under the MIT License.

myli-0.1.2/docs/requirements.in

@@ -0,0 +1,6 @@
+# Top-level documentation dependencies. Keep these versions explicit so that
+# Read the Docs and local builds use the same documentation toolchain.
+Sphinx==8.2.3
+furo==2025.12.19
+myst-parser==5.1.0
+sphinx-copybutton==0.5.2

myli-0.1.2/docs/requirements.txt

@@ -0,0 +1,86 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile docs/requirements.in --python-version 3.12 --output-file docs/requirements.txt
+accessible-pygments==0.0.5
+    # via furo
+alabaster==1.0.0
+    # via sphinx
+babel==2.18.0
+    # via sphinx
+beautifulsoup4==4.15.0
+    # via furo
+certifi==2026.7.22
+    # via requests
+charset-normalizer==3.5.1
+    # via requests
+docutils==0.21.2
+    # via
+    #   myst-parser
+    #   sphinx
+furo==2025.12.19
+    # via -r docs/requirements.in
+idna==3.19
+    # via requests
+imagesize==2.0.0
+    # via sphinx
+jinja2==3.1.6
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==4.2.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==3.0.3
+    # via jinja2
+mdit-py-plugins==0.6.1
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==5.1.0
+    # via -r docs/requirements.in
+packaging==26.3
+    # via sphinx
+pygments==2.21.0
+    # via
+    #   accessible-pygments
+    #   furo
+    #   sphinx
+pyyaml==6.0.3
+    # via myst-parser
+requests==2.34.2
+    # via sphinx
+roman-numerals==4.1.0
+    # via roman-numerals-py
+roman-numerals-py==4.1.0
+    # via sphinx
+snowballstemmer==3.1.1
+    # via sphinx
+soupsieve==2.9.2
+    # via beautifulsoup4
+sphinx==8.2.3
+    # via
+    #   -r docs/requirements.in
+    #   furo
+    #   myst-parser
+    #   sphinx-basic-ng
+    #   sphinx-copybutton
+sphinx-basic-ng==1.0.0b2
+    # via furo
+sphinx-copybutton==0.5.2
+    # via -r docs/requirements.in
+sphinxcontrib-applehelp==2.0.0
+    # via sphinx
+sphinxcontrib-devhelp==2.0.0
+    # via sphinx
+sphinxcontrib-htmlhelp==2.1.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==2.0.0
+    # via sphinx
+sphinxcontrib-serializinghtml==2.0.0
+    # via sphinx
+typing-extensions==4.16.0
+    # via beautifulsoup4
+urllib3==2.7.0
+    # via requests