scry-run 0.1.0__tar.gz

scry_run-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(wc:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run python -m pytest:*)",
+      "Bash(uv sync:*)",
+      "Bash(uv lock:*)"
+    ]
+  }
+}

scry_run-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+__pycache__
+tests/cache.json

scry_run-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: scry-run
+Version: 0.1.0
+Summary: LLM-powered dynamic code generation via metaclasses. Define classes with docstrings, call any method—code generates automatically, caches persistently, and executes instantly.
+Project-URL: Homepage, https://github.com/Tener/scry-run
+Project-URL: Repository, https://github.com/Tener/scry-run
+Author: Krzysztof Skrzętnicki
+License: MIT
+Keywords: ai,claude,code-generation,llm,metaclass
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scry-run
+
+**Write class definitions, get working code.** A Python library where any method call automatically generates its implementation via LLM.
+
+Define your application as a class with a docstring, then call any method you want—`scry-run` generates the code on-demand, caches it, and executes it. No boilerplate, no implementation required.
+
+## Features
+
+- **Zero-boilerplate coding**: Define intent via class docstrings, methods generate automatically
+- **Intelligent caching**: Generated code persists across runs—pay once, use forever
+- **Production-ready**: Bake apps into standalone packages with frozen, pre-generated code
+- **CLI-first**: Manage apps, inspect cache, and export generated code via intuitive commands
+
+## Installation
+
+```bash
+pip install scry-run
+# or with uv
+uv pip install scry-run
+```
+
+### Run without installing (uvx)
+
+```bash
+# From PyPI
+uvx scry-run --help
+uvx scry-run init --name=myapp --description="My app"
+
+# From GitHub (latest)
+uvx --from git+https://github.com/scry-run/scry-run scry-run --help
+```
+
+## Quick Start
+
+### 1. Set up your backend
+
+Requires Claude Code CLI to be installed.
+
+```bash
+# Verify claude CLI is available
+claude --version
+```
+
+### 2. Initialize a project
+
+```bash
+# Non-interactive
+scry-run init --name=todoist --description='minimal web todo app'
+
+# Interactive
+scry-run init
+```
+
+### 3. Run your app
+
+```bash
+scry-run run todoist
+```
+
+Or use it directly in Python:
+
+```python
+from scry_run import ScryClass
+
+class Todoist(ScryClass):
+    """A minimal web todo app with task management."""
+    pass
+
+app = Todoist()
+
+# These methods will be generated automatically!
+app.add_task("Buy groceries")
+app.list_tasks()
+app.complete_task(0)
+```
+
+## Demos
+
+### Creating a simple Hello World app
+
+![Hello Demo](demos/hello.gif)
+
+### Building a maze game with PyGame
+
+![Maze Demo](demos/maze.gif)
+
+
+## How It Works
+
+1. When you access an undefined attribute on an `ScryClass` subclass, the metaclass intercepts it
+2. The library collects the full codebase context and builds a prompt
+3. The configured backend generates code with structured JSON output (code, type, docstring, dependencies)
+4. The code is validated with Python's `ast.parse()` to ensure it's syntactically correct
+5. Valid code is cached and executed
+6. On subsequent accesses, the cached code is used directly
+
+## Backend
+
+Uses Claude Code CLI with `--print` flag for non-interactive output.
+
+```bash
+# If claude CLI is installed, it's used automatically
+scry-run run myapp
+
+# Optionally specify a model
+export SCRY_RUN_MODEL=opus
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SCRY_RUN_BACKEND` | Backend to use: `claude`, `frozen`, or `auto` | `auto` |
+| `SCRY_RUN_MODEL` | Model override (e.g., `opus`) | (backend default) |
+| `SCRY_RUN_MAX_GENERATIONS` | Max code generations per process | `100` |
+
+### Class-level options
+
+```python
+class MyApp(ScryClass):
+    """My application."""
+
+    # Disable LLM generation (raises AttributeError for missing attrs)
+    _llm_enabled = False
+
+    # Use minimal context instead of full codebase (faster)
+    _llm_use_full_context = False
+
+    # Suppress generation messages
+    _llm_quiet = True
+
+    # Override model for this class
+    _llm_model = "opus"
+```
+
+## CLI Commands
+
+### App Management
+
+```bash
+# Initialize a new app
+scry-run init --name=NAME --description=DESC
+
+# List all apps
+scry-run list
+
+# Get path to an app's main file
+scry-run which myapp
+
+# Run an app
+scry-run run myapp [args...]
+
+# Remove an app
+scry-run rm myapp
+scry-run rm myapp --force  # Skip confirmation
+
+# Reset an app (clear code & cache, keep name/description)
+scry-run reset myapp
+scry-run reset myapp --force  # Skip confirmation
+```
+
+### Cache Management
+
+```bash
+# List cached entries for an app
+scry-run cache list myapp
+
+# Show a specific entry
+scry-run cache show myapp MyClass.my_method
+
+# Export cache
+scry-run cache export myapp --output=generated.py --format=python
+scry-run cache export myapp --output=cache.json --format=json
+
+# Remove a specific entry
+scry-run cache rm myapp MyClass.my_method
+
+# Prune cache entries
+scry-run cache prune myapp --class=MyClass --attr=my_method
+scry-run cache prune myapp --class=MyClass  # All methods of a class
+scry-run cache prune myapp --all            # Everything
+
+# Reset cache (clear all entries)
+scry-run cache reset myapp --force
+```
+
+## API
+
+### ScryClass
+
+Base class to inherit from for LLM-powered code generation.
+
+```python
+from scry_run import ScryClass
+
+class MyApp(ScryClass):
+    """Description of your app - the LLM uses this!"""
+
+    def existing_method(self):
+        """Existing methods are used as context."""
+        return "hello"
+
+# Class methods
+MyApp.llm_export_cache("output.py")  # Export generated code
+MyApp.llm_prune_cache("method_name") # Remove cached entry
+MyApp.llm_disable()                   # Disable generation
+MyApp.llm_enable()                    # Re-enable generation
+```
+
+### ScryCache
+
+Manage the code cache programmatically.
+
+```python
+from scry_run import ScryCache
+
+cache = ScryCache()
+
+# Get cached code
+entry = cache.get("MyClass", "my_method")
+print(entry.code)
+
+# List all entries
+for entry in cache.list_entries():
+    print(f"{entry.class_name}.{entry.attr_name}: {entry.docstring}")
+
+# Export
+cache.export_to_file("all_generated_code.py")
+
+# Prune
+cache.prune(class_name="MyClass", attr_name="my_method")
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/scry-run/scry-run
+cd scry-run
+
+# Install with dev dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT

scry_run-0.1.0/README.md

@@ -0,0 +1,252 @@
+# scry-run
+
+**Write class definitions, get working code.** A Python library where any method call automatically generates its implementation via LLM.
+
+Define your application as a class with a docstring, then call any method you want—`scry-run` generates the code on-demand, caches it, and executes it. No boilerplate, no implementation required.
+
+## Features
+
+- **Zero-boilerplate coding**: Define intent via class docstrings, methods generate automatically
+- **Intelligent caching**: Generated code persists across runs—pay once, use forever
+- **Production-ready**: Bake apps into standalone packages with frozen, pre-generated code
+- **CLI-first**: Manage apps, inspect cache, and export generated code via intuitive commands
+
+## Installation
+
+```bash
+pip install scry-run
+# or with uv
+uv pip install scry-run
+```
+
+### Run without installing (uvx)
+
+```bash
+# From PyPI
+uvx scry-run --help
+uvx scry-run init --name=myapp --description="My app"
+
+# From GitHub (latest)
+uvx --from git+https://github.com/scry-run/scry-run scry-run --help
+```
+
+## Quick Start
+
+### 1. Set up your backend
+
+Requires Claude Code CLI to be installed.
+
+```bash
+# Verify claude CLI is available
+claude --version
+```
+
+### 2. Initialize a project
+
+```bash
+# Non-interactive
+scry-run init --name=todoist --description='minimal web todo app'
+
+# Interactive
+scry-run init
+```
+
+### 3. Run your app
+
+```bash
+scry-run run todoist
+```
+
+Or use it directly in Python:
+
+```python
+from scry_run import ScryClass
+
+class Todoist(ScryClass):
+    """A minimal web todo app with task management."""
+    pass
+
+app = Todoist()
+
+# These methods will be generated automatically!
+app.add_task("Buy groceries")
+app.list_tasks()
+app.complete_task(0)
+```
+
+## Demos
+
+### Creating a simple Hello World app
+
+![Hello Demo](demos/hello.gif)
+
+### Building a maze game with PyGame
+
+![Maze Demo](demos/maze.gif)
+
+
+## How It Works
+
+1. When you access an undefined attribute on an `ScryClass` subclass, the metaclass intercepts it
+2. The library collects the full codebase context and builds a prompt
+3. The configured backend generates code with structured JSON output (code, type, docstring, dependencies)
+4. The code is validated with Python's `ast.parse()` to ensure it's syntactically correct
+5. Valid code is cached and executed
+6. On subsequent accesses, the cached code is used directly
+
+## Backend
+
+Uses Claude Code CLI with `--print` flag for non-interactive output.
+
+```bash
+# If claude CLI is installed, it's used automatically
+scry-run run myapp
+
+# Optionally specify a model
+export SCRY_RUN_MODEL=opus
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SCRY_RUN_BACKEND` | Backend to use: `claude`, `frozen`, or `auto` | `auto` |
+| `SCRY_RUN_MODEL` | Model override (e.g., `opus`) | (backend default) |
+| `SCRY_RUN_MAX_GENERATIONS` | Max code generations per process | `100` |
+
+### Class-level options
+
+```python
+class MyApp(ScryClass):
+    """My application."""
+
+    # Disable LLM generation (raises AttributeError for missing attrs)
+    _llm_enabled = False
+
+    # Use minimal context instead of full codebase (faster)
+    _llm_use_full_context = False
+
+    # Suppress generation messages
+    _llm_quiet = True
+
+    # Override model for this class
+    _llm_model = "opus"
+```
+
+## CLI Commands
+
+### App Management
+
+```bash
+# Initialize a new app
+scry-run init --name=NAME --description=DESC
+
+# List all apps
+scry-run list
+
+# Get path to an app's main file
+scry-run which myapp
+
+# Run an app
+scry-run run myapp [args...]
+
+# Remove an app
+scry-run rm myapp
+scry-run rm myapp --force  # Skip confirmation
+
+# Reset an app (clear code & cache, keep name/description)
+scry-run reset myapp
+scry-run reset myapp --force  # Skip confirmation
+```
+
+### Cache Management
+
+```bash
+# List cached entries for an app
+scry-run cache list myapp
+
+# Show a specific entry
+scry-run cache show myapp MyClass.my_method
+
+# Export cache
+scry-run cache export myapp --output=generated.py --format=python
+scry-run cache export myapp --output=cache.json --format=json
+
+# Remove a specific entry
+scry-run cache rm myapp MyClass.my_method
+
+# Prune cache entries
+scry-run cache prune myapp --class=MyClass --attr=my_method
+scry-run cache prune myapp --class=MyClass  # All methods of a class
+scry-run cache prune myapp --all            # Everything
+
+# Reset cache (clear all entries)
+scry-run cache reset myapp --force
+```
+
+## API
+
+### ScryClass
+
+Base class to inherit from for LLM-powered code generation.
+
+```python
+from scry_run import ScryClass
+
+class MyApp(ScryClass):
+    """Description of your app - the LLM uses this!"""
+
+    def existing_method(self):
+        """Existing methods are used as context."""
+        return "hello"
+
+# Class methods
+MyApp.llm_export_cache("output.py")  # Export generated code
+MyApp.llm_prune_cache("method_name") # Remove cached entry
+MyApp.llm_disable()                   # Disable generation
+MyApp.llm_enable()                    # Re-enable generation
+```
+
+### ScryCache
+
+Manage the code cache programmatically.
+
+```python
+from scry_run import ScryCache
+
+cache = ScryCache()
+
+# Get cached code
+entry = cache.get("MyClass", "my_method")
+print(entry.code)
+
+# List all entries
+for entry in cache.list_entries():
+    print(f"{entry.class_name}.{entry.attr_name}: {entry.docstring}")
+
+# Export
+cache.export_to_file("all_generated_code.py")
+
+# Prune
+cache.prune(class_name="MyClass", attr_name="my_method")
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/scry-run/scry-run
+cd scry-run
+
+# Install with dev dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## License
+
+MIT

scry_run-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "scry-run"
+version = "0.1.0"
+description = "LLM-powered dynamic code generation via metaclasses. Define classes with docstrings, call any method—code generates automatically, caches persistently, and executes instantly."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Krzysztof Skrzętnicki" }]
+keywords = ["llm", "code-generation", "metaclass", "claude", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+]
+
+dependencies = [
+    "click>=8.0.0",
+    "rich>=13.0.0",
+    "jinja2>=3.0.0",
+    "tomli>=2.0.0;python_version<'3.11'",
+    "claude-agent-sdk>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-timeout>=2.0.0",
+]
+
+[project.scripts]
+scry-run = "scry_run.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Tener/scry-run"
+Repository = "https://github.com/Tener/scry-run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scry_run"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["demos/"]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+timeout = 30
+timeout_method = "thread"

scry_run-0.1.0/src/scry_run/__init__.py

@@ -0,0 +1,102 @@
+"""scry-run: LLM-powered dynamic code generation via metaclasses."""
+
+from typing import Any
+
+from scry_run.meta import ScryClass, ScryMeta
+from scry_run.cache import ScryCache
+from scry_run.home import get_home, get_app_dir, ensure_home_exists
+from scry_run.config import Config, load_config
+from scry_run.generator import (
+    CodeGenerator,
+    ScryRunError,
+    APIKeyError,
+    RateLimitError,
+    QuotaExceededError,
+    ModelNotFoundError,
+    ContentBlockedError,
+    NetworkError,
+    CodeGenerationError,
+    CodeValidationError,
+)
+from scry_run.context import ContextBuilder
+from scry_run.backends.frozen import FrozenAppError
+
+
+def scry_create(name: str, description: str = "") -> type:
+    """Create a new ScryClass subclass dynamically.
+    
+    Use this to create multiple classes without manually defining them.
+    
+    Args:
+        name: Class name (e.g., "TodoItem", "Database")
+        description: Docstring describing what this class does
+        
+    Returns:
+        A new class inheriting from ScryClass
+        
+    Example:
+        >>> TodoItem = scry_create("TodoItem", "A single todo item with title and status")
+        >>> item = TodoItem("Buy groceries")
+        >>> item.mark_done()  # auto-generated!
+    """
+    doc = description or f"Auto-generated {name} class"
+    return type(name, (ScryClass,), {"__doc__": doc})
+
+
+def is_generated(obj: Any) -> bool:
+    """Check if an object (function, method, property, class) was generated by scry-run.
+    
+    This function reliably checks for internal metadata attached to generated code.
+    It handles unwrapping of properties, classmethods, and bound methods.
+    
+    Args:
+        obj: The object to check
+        
+    Returns:
+        True if the object was generated by LLM, False otherwise.
+    """
+    marker = "_llm_is_generated"
+    
+    # Handle descriptors (property, classmethod, staticmethod)
+    if isinstance(obj, property) and obj.fget:
+        return getattr(obj.fget, marker, False)
+    
+    if isinstance(obj, (classmethod, staticmethod)):
+        return getattr(obj.__func__, marker, False)
+        
+    # Handle bound methods (e.g. instance.method)
+    if hasattr(obj, "__func__"):
+        return getattr(obj.__func__, marker, False)
+        
+    # Handle plain functions/classes
+    return getattr(obj, marker, False)
+
+
+__version__ = "0.1.0"
+__all__ = [
+    "ScryClass",
+    "ScryMeta",
+    "ScryCache",
+    "CodeGenerator",
+    "ContextBuilder",
+    "scry_create",
+    "is_generated",
+    # Home directory
+    "get_home",
+    "get_app_dir",
+    "ensure_home_exists",
+    # Config
+    "Config",
+    "load_config",
+    # Exceptions
+    "ScryRunError",
+    "APIKeyError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ModelNotFoundError",
+    "ContentBlockedError",
+    "NetworkError",
+    "CodeGenerationError",
+    "CodeValidationError",
+    "FrozenAppError",
+]

scry_run-0.1.0/src/scry_run/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Pluggable backend system for LLM code generation."""
+
+from scry_run.backends.base import GeneratorBackend
+from scry_run.backends.registry import get_backend, register_backend
+
+__all__ = ["GeneratorBackend", "get_backend", "register_backend"]