dynra 0.1.1__tar.gz

dynra-0.1.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.

dynra-0.1.1/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: dynra
+Version: 0.1.1
+Summary: Live Python runtime for LLM coding agents
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/antlobach/Dynra
+Project-URL: Documentation, https://github.com/antlobach/Dynra#readme
+Project-URL: Repository, https://github.com/antlobach/Dynra
+Project-URL: Issues, https://github.com/antlobach/Dynra/issues
+Keywords: development,live-coding,mcp,repl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+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 :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipython>=8.0
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/dynra-logo.svg" alt="Dynra" width="860">
+</p>
+
+<p align="center">
+  <strong>Live Python runtime for coding agents.</strong><br>
+  Inspect, patch, and verify running software without restarting the process or losing its state.
+</p>
+
+<p align="center">
+  <a href="https://github.com/antlobach/Dynra/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/antlobach/Dynra/ci.yml?branch=main&amp;style=flat-square&amp;label=tests" alt="Tests" height="20"></a>
+  <a href="https://github.com/antlobach/Dynra/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-%E2%89%A565%25-brightgreen?style=flat-square" alt="Coverage ≥65%" height="20"></a>
+  <img src="https://img.shields.io/badge/python-3.10--3.14-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" alt="Python 3.10–3.14" height="20">
+  <a href="https://github.com/antlobach/Dynra/releases/latest"><img src="https://img.shields.io/github/v/release/antlobach/Dynra?style=flat-square&amp;display_name=tag&amp;cacheSeconds=300" alt="Latest release" height="20"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/antlobach/Dynra?style=flat-square" alt="Apache-2.0 license" height="20"></a>
+  <a href="https://deepwiki.com/antlobach/Dynra"><img src="assets/deepwiki-badge.svg" alt="Ask DeepWiki" height="20"></a>
+</p>
+
+## Overview
+
+Dynra lets a coding agent develop Python software interactively inside a persistent process. The agent can navigate project modules, execute arbitrary Python in their namespaces, add or redefine functions and classes, and exercise each change immediately against the running application.
+
+Compatible function and class identities stay stable while the software evolves. Existing imports, registries, closures, partials, and class instances can continue to refer to the patched objects.
+
+```mermaid
+flowchart LR
+    A[Coding agent] -->|dynra_repl| M[MCP adapter]
+    M --> R[Long-lived IPython process]
+    R --> N[Project module namespaces]
+    R --> P[Live patch engine]
+    P --> O[Existing references and instances]
+    O --> V[Verification against preserved state]
+    V --> A
+```
+
+## Capabilities
+
+- Discovers modules from the repository root, `src/`, and configured setuptools, Poetry, or Hatch source roots.
+- Lists an unloaded module's public symbols without importing it.
+- Executes arbitrary Python in a selected module namespace.
+- Preserves compatible function and class identities across redefinitions.
+- Updates existing imported references and mutable holders.
+- Migrates existing instances through an optional `__dynra_update__` hook.
+- Skips registration decorators when replacing an existing decorated definition.
+- Rolls back definition changes when a multi-definition evaluation fails.
+- Shows, reverts, and persists live changes.
+
+## Install and start
+
+Add Dynra as a development dependency of the target project:
+
+```bash
+cd /path/to/target-project
+uv add --dev dynra
+```
+
+Start Dynra from the target project's root:
+
+```bash
+uv run dynra
+```
+
+Dynra runs in the target project's virtual environment, so project dependencies
+are importable. It reads the target's `pyproject.toml`, activates its source
+roots, and indexes its Python modules without importing them. Dynra does not
+start the application; import or bootstrap the application explicitly when its
+live state is needed. The runtime listens on `127.0.0.1:9999` by default. Use
+`uv run dynra --port PORT` to select another port.
+
+## Agents
+
+The repository includes a [Dynra agent skill](.agents/skills/dynra/SKILL.md). Give that skill to an agent that can call the MCP server. It defines the live-development loop, patching constraints, failure handling, and the point at which a verified live change should become a source edit.
+
+In a project-local MCP configuration, run the installed adapter through the
+project environment:
+
+```json
+{
+  "mcpServers": {
+    "dynra": {
+      "command": "uv",
+      "args": ["run", "dynra-mcp"]
+    }
+  }
+}
+```
+
+The MCP client must launch this command with the target project as its working
+directory. If the configuration is global, set its supported `cwd` option to
+the target project. Start `uv run dynra` separately before using the tool.
+
+The adapter exposes one tool:
+
+```text
+dynra_repl(code, module="user", create=False, port=9999)
+```
+
+`port` selects an existing long-running Dynra/IPython process on `127.0.0.1`; it does not start a new process. The value must match the runtime's `dynra --port PORT` option. `module` selects the namespace before evaluation. Imports are strict, so missing modules and import-time failures return errors. Set `create=True` only for an intentional synthetic scratch module. Responses always contain `success`. Dynra includes `result`, `stdout`, `stderr`, and `error` only when they carry information, and includes `source_sync` only for live changes, healing, conflicts, or source errors. An absent `source_sync` means the selected module is clean.
+
+### Agent workflow
+
+1. Discover the project's modules without importing them.
+2. Enter a module and inspect its live namespace.
+3. Execute focused expressions to explore behavior or build the next increment.
+4. Add or redefine a complete function or class in its owning module.
+5. Exercise the change through a real consumer while process state remains alive.
+6. Inspect the live-versus-disk diff.
+7. Persist the definition or apply the equivalent source edit, then run the project's durable checks.
+
+Example:
+
+```text
+dynra_repl(code="ls_md()")
+dynra_repl(code="dir_md('shop.pricing')")
+
+dynra_repl(
+  module="shop.pricing",
+  code="source(calculate_total)",
+)
+
+dynra_repl(
+  module="shop.pricing",
+  code="def calculate_total(cart):\n    return sum(item.price * item.quantity for item in cart)",
+)
+
+dynra_repl(
+  module="shop.checkout",
+  code="active_checkout.total()",
+  port=9999,
+)
+
+dynra_repl(
+  module="shop.pricing",
+  code="source_patch()",
+)
+```
+
+A successful live patch proves the behavior in the current process. It does not replace source control or the project's test suite.
+
+## Namespace model
+
+Dynra starts in a synthetic `user` namespace. Use the `module` argument on `dynra_repl` for atomic namespace selection. Within the REPL, these commands manage namespaces:
+
+- `require_md(name)` imports a real module and preserves the original import failure.
+- `create_md(name)` creates a synthetic namespace without entering it.
+- `in_md(name)` enters an existing real or synthetic namespace.
+- `ls_md()` separates discovered, loaded-project, synthetic, and external modules.
+- `dir_md(name)` statically inspects an unloaded project module or lists a loaded module.
+
+Dynra supplies its commands through REPL builtins. It does not add those names to application module globals.
+
+## Source healing
+
+Before each evaluation, Dynra checks the source-file signatures of tracked project modules. The clean path performs metadata checks only. Dynra parses a file after its signature changes.
+
+External edits to top-level functions and classes are applied automatically to the existing live objects. Prior imports and compatible instances therefore receive the new behavior without module reloads. Added definitions are evaluated in the live namespace. Deleted definitions are removed from the owning module and direct module imports. Each healed batch increments the module generation and appears in the response's `source_sync` field.
+
+A module can repair derived state through an opt-in hook:
+
+```python
+def __dynra_reconcile__(changes):
+    if any(change[\"definition\"].endswith(\".build_routes\") for change in changes):
+        rebuild_routes_in_place()
+```
+
+Dynra does not rerun arbitrary assignments, imports, or top-level side effects. Constants and copied values retain normal Python semantics. If both disk and the REPL changed the same definition, Dynra keeps the live definition and reports a conflict instead of guessing. `persist_source()` uses the captured base definition and refuses to overwrite an external edit.
+
+## Live patch model
+
+Remote code executes one top-level statement at a time. After each function or class definition, Dynra reconciles the new object with the live object:
+
+- Safe function mode refuses incompatible closure layouts and sync/async changes when old objects still have direct holders.
+- Safe class mode refuses incompatible metaclass, base-class, and `__slots__` changes.
+- Existing decorated definitions retain their registration because Dynra does not rerun their decorators.
+- A multi-definition request restores changed definitions if a definition is refused or evaluation fails.
+
+Transactions cover definition changes. They cannot undo arbitrary external side effects from ordinary statements or a first-time decorator. Native extension state, process configuration, and incompatible object layouts can still require a restart.
+
+### Evolving existing instances
+
+Add `__dynra_update__` when a compatible class patch needs to initialize state on existing instances:
+
+```python
+class Session:
+    def __init__(self, user):
+        self.user = user
+
+    def label(self):
+        return f"{self.user}:{self.status}"
+
+    def __dynra_update__(self):
+        if not hasattr(self, "status"):
+            self.status = "active"
+```
+
+After the patch, existing `Session` instances use the new methods and run `__dynra_update__`.
+
+## Runtime commands
+
+| Command | Purpose |
+| --- | --- |
+| `create_md(name)` | Create a synthetic scratch module. |
+| `require_md(name)` | Import a real module and surface its complete import error. |
+| `in_md(name)` | Enter an existing real or synthetic module. |
+| `ls_md()` | List discovered, loaded-project, synthetic, and external modules. |
+| `dir_md(module=None)` | List symbols, including static inspection of unloaded project modules. |
+| `doc(obj)` / `source(obj)` | Show documentation or live source. |
+| `find_var(pattern)` | Search loaded modules for matching symbol names. |
+| `function_patch_mode(mode=None)` | Read or set `safe` or `permissive` function patching. |
+| `class_patch_mode(mode=None)` | Read or set `safe` or `permissive` class patching. |
+| `unmap(name)` | Delete a binding and report remaining direct holders and qualified module aliases. |
+| `patch_log()` | Show applied, refused, reverted, and persisted operations. |
+| `revert(target)` / `revert_all()` | Restore one or all live definition snapshots; `target` may be the live function/class object or a qualified name. |
+| `diverged()` / `source_patch()` | Show unified diffs between live definitions and source files. |
+| `persist_source(target=None)` | Write exact evaluated definitions to their project source files. |
+| `source_sync_status(module=None)` | Show source freshness, conflicts, live definitions, and generation. |
+| `help_dynra()` | Show runtime help. |
+
+## Terminal client
+
+The interactive runtime accepts normal IPython input. `dynra-client` sends a one-off evaluation to an existing runtime:
+
+```bash
+dynra-client --module package.module "expression"
+dynra-client --module scratch --create "value = 1"
+```
+
+## Security
+
+Dynra executes arbitrary Python by design. Use it only for trusted local development. Do not expose its TCP port to untrusted networks, and do not grant untrusted agents access to the MCP server.
+
+## Development
+
+Develop Dynra in its own environment:
+
+```bash
+git clone https://github.com/antlobach/Dynra.git
+cd Dynra
+uv sync --frozen --group dev
+uv run pytest -q
+uv build
+```
+
+To exercise an unreleased checkout from another project, install it there as an
+editable development dependency:
+
+```bash
+cd /path/to/target-project
+uv add --dev --editable /path/to/Dynra
+uv run dynra
+```
+
+Before committing that project's dependency files, replace the local path with
+the published package:
+
+```bash
+uv remove --dev dynra
+uv add --dev dynra
+```
+
+CI runs the test suite on Python 3.10 through 3.14 and builds the package.
+
+## License
+
+Dynra is licensed under the [Apache License 2.0](LICENSE).