wishful 0.1.0__tar.gz

wishful-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.3
+Name: wishful
+Version: 0.1.0
+Summary: Wishful thinking for Python
+Author: Pyro
+Author-email: Pyro <pyros.sd.models@gmail.com>
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pytest>=8.3.0 ; extra == 'test'
+Requires-Python: >=3.12
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# wishful 🪄
+
+> _"Code so good, you'd think it was wishful thinking"_
+
+Stop writing boilerplate. Start wishing for it instead.
+
+**wishful** turns your wildest import dreams into reality. Just write the import you _wish_ existed, and an LLM conjures up the code on the spot. The first run? Pure magic. Every run after? Blazing fast, because it's cached like real Python.
+
+Think of it as **wishful thinking, but for imports**. The kind that actually works.
+
+## ✨ Quick Wish
+
+**1. Install the dream**
+
+```bash
+pip install wishful
+```
+
+**2. Set your credentials** (litellm reads the usual suspects)
+
+Export them or toss them in a `.env` file—we'll find them:
+
+
+```bash
+export OPENAI_API_KEY=... 
+export DEFAULT_MODEL=azure/gpt-4.1
+``
+
+or
+
+```bash
+export AZURE_API_KEY=...
+export AZURE_API_BASE=https://<your-endpoint>.openai.azure.com/
+export AZURE_API_VERSION=2025-04-01-preview
+export DEFAULT_MODEL=azure/gpt-4.1
+```
+
+or any provider else supported by litellm
+
+
+
+
+
+**3. Import your wildest fantasies**
+
+```python
+from wishful.text import extract_emails
+from wishful.dates import to_yyyy_mm_dd
+
+raw = "Contact us at team@example.com or sales@demo.dev"
+print(extract_emails(raw))  # ['team@example.com', 'sales@demo.dev']
+print(to_yyyy_mm_dd("31.12.2025"))  # '2025-12-31'
+```
+
+**What just happened?**
+
+- **First import**: wishful waves its wand 🪄, asks the LLM to write `extract_emails` and `to_yyyy_mm_dd`, validates the code for safety, and caches it to `.wishful/text.py` and `.wishful/dates.py`.
+- **Every subsequent run**: instant. Just regular Python imports. No latency, no drama, no API calls.
+
+It's like having a junior dev who never sleeps and always delivers exactly what you asked for (well, _almost_ always).
+
+---
+
+## 🎯 Wishful Guidance: Help the AI Read Your Mind
+
+Want better results? Drop hints. Literal comments. wishful reads the code _around_ your import and forwards that context to the LLM.
+
+```python
+# desired: parse standard nginx combined logs into list of dicts
+from wishful.logs import parse_nginx_logs
+
+records = parse_nginx_logs(Path("/var/log/nginx/access.log").read_text())
+```
+
+The AI sees your comment and knows _exactly_ what you're after. It's like pair programming, but your partner is a disembodied intelligence with questionable opinions about semicolons.
+
+---
+
+## 🗄️ Cache Ops: Because Sometimes Wishes Need Revising
+
+```python
+import wishful
+
+# See what you've wished for
+wishful.inspect_cache()   # ['.wishful/text.py', '.wishful/dates.py']
+
+# Regret a wish? Regenerate it
+wishful.regenerate("wishful.text")  # Next import re-generates from scratch
+
+# Nuclear option: forget everything
+wishful.clear_cache()  # Deletes the entire .wishful/ directory
+```
+
+The cache is just regular Python files in `.wishful/`. Want to tweak the generated code? Edit it directly. It's your wish, after all.
+
+---
+
+## ⚙️ Configuration: Fine-Tune Your Wishes
+
+```python
+import wishful
+
+wishful.configure(
+    model="gpt-4o-mini",        # Switch models like changing channels
+    cache_dir="/tmp/.wishful",  # Hide your wishes somewhere else
+    spinner=False,              # Silence the "generating..." spinner
+    review=True,                # Paranoid? Review code before it runs
+    allow_unsafe=False,         # Keep the safety rails ON (recommended)
+)
+```
+
+### Environment Variables (for the env-obsessed)
+
+Set these in your shell or `.env` file:
+
+- `WISHFUL_MODEL` / `DEFAULT_MODEL` — which AI overlord to summon
+- `WISHFUL_CACHE_DIR` — where to stash generated wishes (default: `.wishful`)
+- `WISHFUL_REVIEW` — set to `1` to manually approve every wish (trust issues?)
+- `WISHFUL_DEBUG` — verbose logging for when things go sideways
+- `WISHFUL_UNSAFE` — set to `1` to disable safety checks (⚠️ danger zone)
+- `WISHFUL_SPINNER` — set to `0` to disable the fancy spinner
+- `WISHFUL_MAX_TOKENS` — cap the LLM's verbosity (default: 800)
+- `WISHFUL_TEMPERATURE` — creativity dial (default: 0 = boring but safe)
+
+---
+
+## 🛡️ Safety Rails: Wishful Isn't _That_ Reckless
+
+We're not complete anarchists here. Generated code gets AST-scanned to block obviously dangerous patterns:
+
+- ❌ Imports like `os`, `subprocess`, `sys`
+- ❌ Calls to `eval()` or `exec()`
+- ❌ `open()` in write/append mode
+- ❌ Shenanigans like `os.system()` or `subprocess.call()`
+
+**Override at your own peril**: `WISHFUL_UNSAFE=1` or `allow_unsafe=True` turns off the guardrails. We won't judge. (We will _totally_ judge.)
+
+---
+
+## 🧪 Testing: Wishes Without Consequences
+
+Need deterministic, offline behavior? Set `WISHFUL_FAKE_LLM=1` and wishful will generate placeholder stub functions instead of hitting the network.
+
+Perfect for CI, unit tests, or when your Wi-Fi is acting up.
+
+```bash
+export WISHFUL_FAKE_LLM=1
+python my_tests.py  # No API calls, just predictable stubs
+```
+
+---
+
+## 🔮 How the Magic Actually Works
+
+Here's the 30-second version:
+
+1. **Import hook**: wishful installs a `MagicFinder` on `sys.meta_path` that intercepts `wishful.*` imports.
+2. **Cache check**: If `.wishful/<module>.py` exists, it loads instantly. No AI needed.
+3. **LLM generation**: If not cached, wishful calls the LLM (via `litellm`) to generate the code based on your import and surrounding context.
+4. **Validation**: The generated code is AST-parsed and safety-checked (unless you disabled that like a madman).
+5. **Execution**: Code is written to `.wishful/`, compiled, and executed as the import result.
+6. **Transparency**: The cache is just plain Python files. Edit them. Commit them. They're yours.
+
+It's import hooks meets LLMs meets "why didn't this exist already?"
+
+---
+
+## 🎭 Fun with Wishful Thinking
+
+```python
+# Need some cosmic horror? Just wish for it.
+from wishful.story import cosmic_horror_intro
+
+intro = cosmic_horror_intro(
+    setting="a deserted amusement park",
+    word_count_at_least=100
+)
+print(intro)  # 🎢👻
+
+# Math that writes itself
+from wishful.numbers import primes_from_to, sum_list
+
+total = sum_list(list=primes_from_to(1, 100))
+print(total)  # 1060 (probably)
+
+# Because who has time to write date parsers?
+from wishful.dates import parse_fuzzy_date
+
+print(parse_fuzzy_date("next Tuesday"))  # Your guess is as good as mine
+```
+
+---
+
+## 🤔 FAQ (Frequently Asked Wishes)
+
+**Q: Is this production-ready?**  
+A: Define "production." 🙃
+
+**Q: What if the LLM generates bad code?**  
+A: That's what the cache is for. Check `.wishful/`, tweak it, commit it, and it's locked in.
+
+**Q: Can I use this with OpenAI/Claude/local models?**  
+A: Yep! We use `litellm`, so anything it supports, we support.
+
+**Q: What if I import something that doesn't make sense?**  
+A: The LLM will do its best. Results may vary. Hilarity may ensue.
+
+**Q: Is this just lazy programming?**  
+A: It's not lazy. It's _efficient wishful thinking_. 😎
+
+---
+
+## 📜 License
+
+MIT. Wish responsibly.
+
+**Go forth and wish.** ✨
+
+Your imports will never be the same.

wishful-0.1.0/README.md

@@ -0,0 +1,219 @@
+# wishful 🪄
+
+> _"Code so good, you'd think it was wishful thinking"_
+
+Stop writing boilerplate. Start wishing for it instead.
+
+**wishful** turns your wildest import dreams into reality. Just write the import you _wish_ existed, and an LLM conjures up the code on the spot. The first run? Pure magic. Every run after? Blazing fast, because it's cached like real Python.
+
+Think of it as **wishful thinking, but for imports**. The kind that actually works.
+
+## ✨ Quick Wish
+
+**1. Install the dream**
+
+```bash
+pip install wishful
+```
+
+**2. Set your credentials** (litellm reads the usual suspects)
+
+Export them or toss them in a `.env` file—we'll find them:
+
+
+```bash
+export OPENAI_API_KEY=... 
+export DEFAULT_MODEL=azure/gpt-4.1
+``
+
+or
+
+```bash
+export AZURE_API_KEY=...
+export AZURE_API_BASE=https://<your-endpoint>.openai.azure.com/
+export AZURE_API_VERSION=2025-04-01-preview
+export DEFAULT_MODEL=azure/gpt-4.1
+```
+
+or any provider else supported by litellm
+
+
+
+
+
+**3. Import your wildest fantasies**
+
+```python
+from wishful.text import extract_emails
+from wishful.dates import to_yyyy_mm_dd
+
+raw = "Contact us at team@example.com or sales@demo.dev"
+print(extract_emails(raw))  # ['team@example.com', 'sales@demo.dev']
+print(to_yyyy_mm_dd("31.12.2025"))  # '2025-12-31'
+```
+
+**What just happened?**
+
+- **First import**: wishful waves its wand 🪄, asks the LLM to write `extract_emails` and `to_yyyy_mm_dd`, validates the code for safety, and caches it to `.wishful/text.py` and `.wishful/dates.py`.
+- **Every subsequent run**: instant. Just regular Python imports. No latency, no drama, no API calls.
+
+It's like having a junior dev who never sleeps and always delivers exactly what you asked for (well, _almost_ always).
+
+---
+
+## 🎯 Wishful Guidance: Help the AI Read Your Mind
+
+Want better results? Drop hints. Literal comments. wishful reads the code _around_ your import and forwards that context to the LLM.
+
+```python
+# desired: parse standard nginx combined logs into list of dicts
+from wishful.logs import parse_nginx_logs
+
+records = parse_nginx_logs(Path("/var/log/nginx/access.log").read_text())
+```
+
+The AI sees your comment and knows _exactly_ what you're after. It's like pair programming, but your partner is a disembodied intelligence with questionable opinions about semicolons.
+
+---
+
+## 🗄️ Cache Ops: Because Sometimes Wishes Need Revising
+
+```python
+import wishful
+
+# See what you've wished for
+wishful.inspect_cache()   # ['.wishful/text.py', '.wishful/dates.py']
+
+# Regret a wish? Regenerate it
+wishful.regenerate("wishful.text")  # Next import re-generates from scratch
+
+# Nuclear option: forget everything
+wishful.clear_cache()  # Deletes the entire .wishful/ directory
+```
+
+The cache is just regular Python files in `.wishful/`. Want to tweak the generated code? Edit it directly. It's your wish, after all.
+
+---
+
+## ⚙️ Configuration: Fine-Tune Your Wishes
+
+```python
+import wishful
+
+wishful.configure(
+    model="gpt-4o-mini",        # Switch models like changing channels
+    cache_dir="/tmp/.wishful",  # Hide your wishes somewhere else
+    spinner=False,              # Silence the "generating..." spinner
+    review=True,                # Paranoid? Review code before it runs
+    allow_unsafe=False,         # Keep the safety rails ON (recommended)
+)
+```
+
+### Environment Variables (for the env-obsessed)
+
+Set these in your shell or `.env` file:
+
+- `WISHFUL_MODEL` / `DEFAULT_MODEL` — which AI overlord to summon
+- `WISHFUL_CACHE_DIR` — where to stash generated wishes (default: `.wishful`)
+- `WISHFUL_REVIEW` — set to `1` to manually approve every wish (trust issues?)
+- `WISHFUL_DEBUG` — verbose logging for when things go sideways
+- `WISHFUL_UNSAFE` — set to `1` to disable safety checks (⚠️ danger zone)
+- `WISHFUL_SPINNER` — set to `0` to disable the fancy spinner
+- `WISHFUL_MAX_TOKENS` — cap the LLM's verbosity (default: 800)
+- `WISHFUL_TEMPERATURE` — creativity dial (default: 0 = boring but safe)
+
+---
+
+## 🛡️ Safety Rails: Wishful Isn't _That_ Reckless
+
+We're not complete anarchists here. Generated code gets AST-scanned to block obviously dangerous patterns:
+
+- ❌ Imports like `os`, `subprocess`, `sys`
+- ❌ Calls to `eval()` or `exec()`
+- ❌ `open()` in write/append mode
+- ❌ Shenanigans like `os.system()` or `subprocess.call()`
+
+**Override at your own peril**: `WISHFUL_UNSAFE=1` or `allow_unsafe=True` turns off the guardrails. We won't judge. (We will _totally_ judge.)
+
+---
+
+## 🧪 Testing: Wishes Without Consequences
+
+Need deterministic, offline behavior? Set `WISHFUL_FAKE_LLM=1` and wishful will generate placeholder stub functions instead of hitting the network.
+
+Perfect for CI, unit tests, or when your Wi-Fi is acting up.
+
+```bash
+export WISHFUL_FAKE_LLM=1
+python my_tests.py  # No API calls, just predictable stubs
+```
+
+---
+
+## 🔮 How the Magic Actually Works
+
+Here's the 30-second version:
+
+1. **Import hook**: wishful installs a `MagicFinder` on `sys.meta_path` that intercepts `wishful.*` imports.
+2. **Cache check**: If `.wishful/<module>.py` exists, it loads instantly. No AI needed.
+3. **LLM generation**: If not cached, wishful calls the LLM (via `litellm`) to generate the code based on your import and surrounding context.
+4. **Validation**: The generated code is AST-parsed and safety-checked (unless you disabled that like a madman).
+5. **Execution**: Code is written to `.wishful/`, compiled, and executed as the import result.
+6. **Transparency**: The cache is just plain Python files. Edit them. Commit them. They're yours.
+
+It's import hooks meets LLMs meets "why didn't this exist already?"
+
+---
+
+## 🎭 Fun with Wishful Thinking
+
+```python
+# Need some cosmic horror? Just wish for it.
+from wishful.story import cosmic_horror_intro
+
+intro = cosmic_horror_intro(
+    setting="a deserted amusement park",
+    word_count_at_least=100
+)
+print(intro)  # 🎢👻
+
+# Math that writes itself
+from wishful.numbers import primes_from_to, sum_list
+
+total = sum_list(list=primes_from_to(1, 100))
+print(total)  # 1060 (probably)
+
+# Because who has time to write date parsers?
+from wishful.dates import parse_fuzzy_date
+
+print(parse_fuzzy_date("next Tuesday"))  # Your guess is as good as mine
+```
+
+---
+
+## 🤔 FAQ (Frequently Asked Wishes)
+
+**Q: Is this production-ready?**  
+A: Define "production." 🙃
+
+**Q: What if the LLM generates bad code?**  
+A: That's what the cache is for. Check `.wishful/`, tweak it, commit it, and it's locked in.
+
+**Q: Can I use this with OpenAI/Claude/local models?**  
+A: Yep! We use `litellm`, so anything it supports, we support.
+
+**Q: What if I import something that doesn't make sense?**  
+A: The LLM will do its best. Results may vary. Hilarity may ensue.
+
+**Q: Is this just lazy programming?**  
+A: It's not lazy. It's _efficient wishful thinking_. 😎
+
+---
+
+## 📜 License
+
+MIT. Wish responsibly.
+
+**Go forth and wish.** ✨
+
+Your imports will never be the same.

wishful-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "wishful"
+version = "0.1.0"
+description = "Wishful thinking for Python"
+readme = "README.md"
+authors = [
+    { name = "Pyro", email = "pyros.sd.models@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "litellm>=1.40.0",
+    "rich>=13.7.0",
+    "python-dotenv>=1.0.1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.3.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.1,<0.10.0"]
+build-backend = "uv_build"

wishful-0.1.0/src/wishful/__init__.py

@@ -0,0 +1,54 @@
+"""wishful - Just-in-Time code generation via import hooks."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from typing import List
+
+from wishful.cache import manager as cache
+from wishful.config import configure, reset_defaults, settings
+from wishful.core.finder import install as install_finder
+from wishful.llm.client import GenerationError
+from wishful.safety.validator import SecurityError
+
+# Install on import so `import magic.xyz` is intercepted immediately.
+install_finder()
+
+__all__ = [
+    "configure",
+    "clear_cache",
+    "inspect_cache",
+    "regenerate",
+    "SecurityError",
+    "GenerationError",
+]
+
+
+def clear_cache() -> None:
+    """Delete all generated files from the cache directory."""
+
+    cache.clear_cache()
+    # Remove any loaded wishful modules so they regenerate on next import.
+    for name in list(sys.modules):
+        if name.startswith("wishful."):
+            sys.modules.pop(name, None)
+
+
+def inspect_cache() -> List[str]:
+    """Return a list of cached module file paths as strings."""
+
+    return [str(p) for p in cache.inspect_cache()]
+
+
+def regenerate(module_name: str) -> None:
+    """Force regeneration of a module on next import."""
+
+    if not module_name.startswith("wishful"):
+        module_name = f"wishful.{module_name}"
+    cache.delete_cached(module_name)
+    sys.modules.pop(module_name, None)
+    importlib.invalidate_caches()
+
+
+__version__ = "0.1.0"

wishful-0.1.0/src/wishful/cache/__init__.py

@@ -0,0 +1,23 @@
+"""Cache utilities for wishful."""
+
+from .manager import (
+    clear_cache,
+    delete_cached,
+    ensure_cache_dir,
+    has_cached,
+    inspect_cache,
+    module_path,
+    read_cached,
+    write_cached,
+)
+
+__all__ = [
+    "read_cached",
+    "write_cached",
+    "clear_cache",
+    "inspect_cache",
+    "module_path",
+    "ensure_cache_dir",
+    "delete_cached",
+    "has_cached",
+]

wishful-0.1.0/src/wishful/cache/manager.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+from wishful.config import settings
+
+
+def module_path(fullname: str) -> Path:
+    # Strip leading namespace "wishful" and map dots to directories.
+    parts = fullname.split(".")
+    if parts[0] == "wishful":
+        parts = parts[1:]
+    relative = Path(*parts) if parts else Path("__init__")
+    return settings.cache_dir / relative.with_suffix(".py")
+
+
+def ensure_cache_dir() -> Path:
+    settings.cache_dir.mkdir(parents=True, exist_ok=True)
+    return settings.cache_dir
+
+
+def read_cached(fullname: str) -> Optional[str]:
+    path = module_path(fullname)
+    if path.exists():
+        return path.read_text()
+    return None
+
+
+def write_cached(fullname: str, source: str) -> Path:
+    path = module_path(fullname)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(source)
+    return path
+
+
+def delete_cached(fullname: str) -> None:
+    path = module_path(fullname)
+    if path.exists():
+        path.unlink()
+
+
+def clear_cache() -> None:
+    if settings.cache_dir.exists():
+        shutil.rmtree(settings.cache_dir)
+
+
+def inspect_cache() -> List[Path]:
+    if not settings.cache_dir.exists():
+        return []
+    return sorted(settings.cache_dir.rglob("*.py"))
+
+
+def has_cached(fullname: str) -> bool:
+    return module_path(fullname).exists()

wishful-0.1.0/src/wishful/config.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from dotenv import load_dotenv
+
+# Load environment variables from a local .env if present so users don't need to
+# export them manually when running examples.
+load_dotenv()
+
+
+_DEFAULT_MODEL = os.getenv("DEFAULT_MODEL", os.getenv("WISHFUL_MODEL", "azure/gpt-4.1"))
+
+
+@dataclass
+class Settings:
+    """Runtime configuration for wishful.
+
+    Values are mutable at runtime via :func:`configure` to make tests and user
+    code ergonomics-friendly. Defaults are sourced from environment variables.
+    """
+
+    model: str = _DEFAULT_MODEL
+    cache_dir: Path = field(default_factory=lambda: Path(os.getenv("WISHFUL_CACHE_DIR", ".wishful")))
+    review: bool = os.getenv("WISHFUL_REVIEW", "0") == "1"
+    debug: bool = os.getenv("WISHFUL_DEBUG", "0") == "1"
+    allow_unsafe: bool = os.getenv("WISHFUL_UNSAFE", "0") == "1"
+    spinner: bool = os.getenv("WISHFUL_SPINNER", "1") != "0"
+    max_tokens: int = int(os.getenv("WISHFUL_MAX_TOKENS", "800"))
+    temperature: float = float(os.getenv("WISHFUL_TEMPERATURE", "0"))
+
+    def copy(self) -> "Settings":
+        return Settings(
+            model=self.model,
+            cache_dir=self.cache_dir,
+            review=self.review,
+            debug=self.debug,
+            allow_unsafe=self.allow_unsafe,
+            spinner=self.spinner,
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+        )
+
+
+settings = Settings()
+
+
+def configure(
+    *,
+    model: Optional[str] = None,
+    cache_dir: Optional[str | Path] = None,
+    review: Optional[bool] = None,
+    debug: Optional[bool] = None,
+    allow_unsafe: Optional[bool] = None,
+    spinner: Optional[bool] = None,
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+) -> None:
+    """Update global settings in-place.
+
+    All parameters are optional; only provided values overwrite current
+    settings. Accepts both strings and :class:`pathlib.Path` for `cache_dir`.
+    """
+
+    if model is not None:
+        settings.model = model
+    if cache_dir is not None:
+        settings.cache_dir = Path(cache_dir)
+    if review is not None:
+        settings.review = review
+    if debug is not None:
+        settings.debug = debug
+    if allow_unsafe is not None:
+        settings.allow_unsafe = allow_unsafe
+    if spinner is not None:
+        settings.spinner = spinner
+    if temperature is not None:
+        settings.temperature = temperature
+    if max_tokens is not None:
+        settings.max_tokens = max_tokens
+
+
+def reset_defaults() -> None:
+    """Reset settings to environment-driven defaults (useful for tests)."""
+
+    global settings
+    settings = Settings()

wishful-0.1.0/src/wishful/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core import machinery for wishful."""
+
+from .finder import MagicFinder, install
+from .loader import MagicLoader
+
+__all__ = ["MagicFinder", "MagicLoader", "install"]

wishful-0.1.0/src/wishful/core/discovery.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import ast
+import inspect
+import linecache
+from pathlib import Path
+from textwrap import dedent
+from typing import List, Optional, Sequence, Tuple
+
+
+class ImportContext:
+    def __init__(self, functions: Sequence[str], context: str | None):
+        self.functions = list(functions)
+        self.context = context
+
+    def __repr__(self) -> str:  # pragma: no cover - debug helper
+        return f"ImportContext(functions={self.functions}, context={self.context!r})"
+
+
+def _gather_context_lines(filename: str, lineno: int, radius: int = 2) -> str:
+    lines = linecache.getlines(filename)
+    if not lines:
+        return ""
+    start = max(lineno, 1) - 1
+    end = min(lineno + radius, len(lines))
+    snippet = lines[start:end]
+    return "".join(snippet).strip()
+
+
+def _parse_imported_names(source_line: str, fullname: str) -> List[str]:
+    try:
+        tree = ast.parse(dedent(source_line))
+    except SyntaxError:
+        return []
+
+    names: List[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if node.module and node.module.startswith("wishful") and fullname.startswith(node.module):
+                for alias in node.names:
+                    # Use original name (not alias) because that's what the module must define.
+                    names.append(alias.name)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name.startswith("wishful") and fullname.startswith(alias.name):
+                    # For `import wishful.foo as bar`, the target is bar (module).
+                    target = alias.asname or alias.name.split(".")[-1]
+                    names.append(target)
+    return names
+
+
+def discover(fullname: str) -> ImportContext:
+    """Attempt to recover requested symbol names and nearby comments.
+
+    This uses stack inspection heuristics. It is best-effort; absence of
+    signals simply results in empty context.
+    """
+
+    frame = inspect.currentframe()
+    # Skip the discover() frame itself.
+    if frame:
+        frame = frame.f_back
+
+    while frame:
+        filename = frame.f_code.co_filename
+        lineno = frame.f_lineno
+
+        if filename.startswith("<"):
+            frame = frame.f_back
+            continue
+        normalized = filename.replace("\\", "/")
+        if "/src/wishful/" in normalized and "/tests/" not in normalized:
+            frame = frame.f_back
+            continue
+
+        code_line = linecache.getline(filename, lineno).strip()
+        if code_line:
+            functions = _parse_imported_names(code_line, fullname)
+            if functions:
+                context = _gather_context_lines(filename, lineno + 1, radius=3)
+                return ImportContext(functions=functions, context=context)
+
+        frame = frame.f_back
+
+    return ImportContext(functions=[], context=None)

wishful-0.1.0/src/wishful/core/finder.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import importlib.abc
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Optional
+
+from wishful.core.loader import MagicLoader, MagicPackageLoader
+
+
+MAGIC_NAMESPACE = "wishful"
+
+
+class MagicFinder(importlib.abc.MetaPathFinder):
+    """Intercept imports for the `wishful.*` namespace."""
+
+    def find_spec(self, fullname: str, path, target=None):
+        if not fullname.startswith(MAGIC_NAMESPACE):
+            return None
+        
+        # Check if this module actually exists on disk as part of our package
+        # If it does, let the default import mechanism handle it
+        parts = fullname.split('.')
+        if len(parts) >= 2:
+            # Check for our internal package modules
+            module_file = Path(__file__).parent.parent / parts[1]
+            if module_file.exists() or (module_file.with_suffix('.py')).exists():
+                return None
+
+        if fullname == MAGIC_NAMESPACE:
+            return importlib.util.spec_from_loader(fullname, MagicPackageLoader(), is_package=True)
+
+        loader = MagicLoader(fullname)
+        return importlib.util.spec_from_loader(fullname, loader, is_package=False)
+
+
+def install() -> None:
+    """Register the finder if it is not already present."""
+
+    for finder in list(__import__("sys").meta_path):  # type: ignore
+        if isinstance(finder, MagicFinder):
+            return
+    __import__("sys").meta_path.insert(0, MagicFinder())

wishful-0.1.0/src/wishful/core/loader.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import importlib.abc
+import importlib.util
+import sys
+from types import ModuleType
+from typing import Optional, Sequence
+
+from wishful.cache import manager as cache
+from wishful.config import settings
+from wishful.core.discovery import discover
+from wishful.llm.client import GenerationError, generate_module_code
+from wishful.safety.validator import SecurityError, validate_code
+from wishful.ui import spinner
+
+
+class MagicLoader(importlib.abc.Loader):
+    """Loader that returns dynamic modules backed by cache + LLM generation."""
+
+    def __init__(self, fullname: str):
+        self.fullname = fullname
+
+    def create_module(self, spec):  # pragma: no cover - default works
+        return None
+
+    def exec_module(self, module: ModuleType) -> None:
+        context = discover(self.fullname)
+        functions = context.functions
+
+        source = cache.read_cached(self.fullname)
+        from_cache = source is not None
+
+        if source is None:
+            source = self._generate_and_cache(functions, context)
+
+        self._exec_source(source, module)
+
+        # If cached code is missing requested symbols, regenerate once.
+        if functions:
+            missing = [name for name in functions if name not in module.__dict__]
+            if missing:
+                if from_cache:
+                    desired = sorted(set(functions) | self._declared_symbols(module))
+                    cache.delete_cached(self.fullname)
+                    source = self._generate_and_cache(desired, context)
+                    self._exec_source(source, module, clear_first=True)
+                else:
+                    raise GenerationError(
+                        f"Generated module for {self.fullname} lacks symbols: {', '.join(missing)}"
+                    )
+
+        self._attach_dynamic_getattr(module)
+
+        if settings.review:
+            print(f"Generated code for {self.fullname}:\n{source}\n")
+            answer = input("Run this code? [y/N]: ")
+            if answer.lower().strip() not in {"y", "yes"}:
+                cache.delete_cached(self.fullname)
+                raise ImportError("User rejected generated code.")
+
+    def _generate_and_cache(self, functions, context):
+        with spinner(f"Generating {self.fullname}"):
+            source = generate_module_code(self.fullname, functions, context.context)
+        cache.write_cached(self.fullname, source)
+        return source
+
+    def _exec_source(self, source: str, module: ModuleType, clear_first: bool = False) -> None:
+        try:
+            validate_code(source, allow_unsafe=settings.allow_unsafe)
+        except SecurityError:
+            raise
+        if clear_first:
+            module.__dict__.clear()
+        module.__file__ = str(cache.module_path(self.fullname))
+        module.__package__ = self.fullname.rpartition('.')[0]
+        exec(compile(source, module.__file__, "exec"), module.__dict__)
+
+    def _attach_dynamic_getattr(self, module: ModuleType) -> None:
+        def _dynamic_getattr(name: str):
+            if name.startswith("__"):
+                raise AttributeError(name)
+
+            ctx = discover(self.fullname)
+            functions = set(ctx.functions or [])
+            declared = self._declared_symbols(module)
+            desired = sorted(declared | functions | {name})
+
+            source = self._generate_and_cache(desired, ctx)
+            self._exec_source(source, module, clear_first=True)
+            # Re-attach for future misses after reload
+            module.__getattr__ = _dynamic_getattr
+            if name in module.__dict__:
+                return module.__dict__[name]
+            raise AttributeError(name)
+
+        module.__getattr__ = _dynamic_getattr
+
+    @staticmethod
+    def _declared_symbols(module: ModuleType) -> set[str]:
+        return {k for k in module.__dict__ if not k.startswith("__")}
+
+
+class MagicPackageLoader(importlib.abc.Loader):
+    """Loader for the root 'wishful' package to enable namespace imports."""
+
+    def create_module(self, spec):  # pragma: no cover - default create
+        return None
+
+    def exec_module(self, module: ModuleType) -> None:
+        module.__path__ = [str(cache.ensure_cache_dir())]
+        module.__package__ = "wishful"
+        module.__file__ = str(cache.ensure_cache_dir() / "__init__.py")

wishful-0.1.0/src/wishful/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM integration layer."""
+
+from .client import generate_module_code, GenerationError
+
+__all__ = ["generate_module_code", "GenerationError"]

wishful-0.1.0/src/wishful/llm/client.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+from typing import List, Sequence
+
+import litellm
+
+from wishful.config import settings
+from wishful.llm.prompts import build_messages, strip_code_fences
+
+
+class GenerationError(ImportError):
+    """Raised when the LLM call fails or returns empty output."""
+
+
+_FAKE_MODE = os.getenv("WISHFUL_FAKE_LLM", "0") == "1"
+
+
+def _fake_response(functions: Sequence[str]) -> str:
+    body = []
+    for name in functions or ("generated_helper",):
+        body.append(
+            f"def {name}(*args, **kwargs):\n    \"\"\"Auto-generated placeholder. Replace with real logic.\"\"\"\n    return {{'args': args, 'kwargs': kwargs}}\n"
+        )
+    return "\n\n".join(body)
+
+
+def generate_module_code(module: str, functions: Sequence[str], context: str | None) -> str:
+    """Call the LLM (or fake stub) to generate module source code."""
+
+    if _FAKE_MODE:
+        return _fake_response(functions)
+
+    messages = build_messages(module, functions, context)
+    try:
+        response = litellm.completion(
+            model=settings.model,
+            messages=messages,
+            temperature=settings.temperature,
+            max_tokens=settings.max_tokens,
+        )
+    except Exception as exc:  # pragma: no cover - network path not executed in tests
+        raise GenerationError(f"LLM call failed: {exc}") from exc
+
+    try:
+        content = response["choices"][0]["message"]["content"]
+    except Exception as exc:  # pragma: no cover
+        raise GenerationError("Unexpected LLM response structure") from exc
+
+    if not content or not content.strip():
+        raise GenerationError("LLM returned empty content")
+
+    return strip_code_fences(content).strip()

wishful-0.1.0/src/wishful/llm/prompts.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import Iterable, List, Sequence
+
+
+def build_messages(module: str, functions: Sequence[str], context: str | None) -> List[dict]:
+    func_list = ", ".join(functions) if functions else "" "module-level helpers" ""
+    user_parts = [f"Module: {module}"]
+    if functions:
+        user_parts.append(f"Functions to implement: {', '.join(functions)}")
+    if context:
+        user_parts.append("Context:\n" + context.strip())
+
+    user_prompt = "\n\n".join(user_parts)
+
+    system = dedent(
+        """
+        You are a Python code generator. Output ONLY executable Python code.
+        - Do not wrap code in markdown fences.
+        - Only use the Python standard library.
+        - Prefer simple, readable implementations.
+        - Avoid network, filesystem writes, subprocess, or shell execution.
+        - Include docstrings and type hints where helpful.
+        """
+    ).strip()
+
+    return [
+        {"role": "system", "content": system},
+        {"role": "user", "content": user_prompt},
+    ]
+
+
+def strip_code_fences(text: str) -> str:
+    """Remove Markdown code fences if present."""
+
+    if "```" not in text:
+        return text
+
+    parts = text.split("```")
+    if len(parts) >= 3:
+        # content between first and second fence
+        return parts[1].strip('\n') if parts[0].strip() == "" else parts[1]+parts[2]
+    return text

wishful-0.1.0/src/wishful/safety/__init__.py

@@ -0,0 +1,5 @@
+"""Safety checks for generated code."""
+
+from .validator import validate_code, SecurityError
+
+__all__ = ["validate_code", "SecurityError"]

wishful-0.1.0/src/wishful/safety/validator.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import ast
+from typing import Iterable, Set
+
+
+class SecurityError(ImportError):
+    """Raised when generated code violates safety policy."""
+
+
+_FORBIDDEN_IMPORTS = {"os", "subprocess", "sys"}
+_FORBIDDEN_CALLS = {"eval", "exec"}
+_FORBIDDEN_FUNCTIONS = {"open"}
+
+
+def _collect_names(node: ast.AST) -> Set[str]:
+    names = set()
+    for child in ast.walk(node):
+        if isinstance(child, ast.Name):
+            names.add(child.id)
+    return names
+
+
+def validate_code(source: str, *, allow_unsafe: bool = False) -> None:
+    """Perform light-weight static checks on generated code.
+
+    The goal is to block obviously dangerous constructs without being overly
+    restrictive. Users can opt-out by setting `allow_unsafe=True`.
+    """
+
+    if allow_unsafe:
+        return
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:  # surface errors early
+        raise ImportError(f"Generated code has syntax error: {exc}") from exc
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name.split(".")[0] in _FORBIDDEN_IMPORTS:
+                    raise SecurityError(f"Forbidden import: {alias.name}")
+        elif isinstance(node, ast.ImportFrom):
+            if node.module and node.module.split(".")[0] in _FORBIDDEN_IMPORTS:
+                raise SecurityError(f"Forbidden import: {node.module}")
+        elif isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name):
+                func_name = node.func.id
+                if func_name in _FORBIDDEN_CALLS:
+                    raise SecurityError(f"Forbidden call: {func_name}()")
+                if func_name == "open":
+                    # Evaluate mode argument safety (write modes contain 'w', 'a', '+').
+                    if node.args:
+                        first_arg = node.args[0]
+                        if isinstance(first_arg, ast.Constant) and isinstance(first_arg.value, str):
+                            mode_arg = None
+                            if len(node.args) > 1 and isinstance(node.args[1], ast.Constant):
+                                mode_arg = node.args[1].value
+                            elif node.keywords:
+                                for kw in node.keywords:
+                                    if kw.arg == "mode" and isinstance(kw.value, ast.Constant):
+                                        mode_arg = kw.value.value
+                            if mode_arg and any(ch in str(mode_arg) for ch in "wa+"):
+                                raise SecurityError("open() in write/append mode is blocked")
+            if isinstance(node.func, ast.Attribute):
+                # Block os.system / subprocess.call etc even if imported under alias.
+                attr_chain = []
+                current = node.func
+                while isinstance(current, ast.Attribute):
+                    attr_chain.append(current.attr)
+                    current = current.value
+                if isinstance(current, ast.Name):
+                    attr_chain.append(current.id)
+                    dotted = ".".join(reversed(attr_chain))
+                    if dotted.startswith("os.") or dotted.startswith("subprocess."):
+                        raise SecurityError(f"Forbidden call: {dotted}()")
+
+    # Additional rule: do not allow top-level exec/eval in any alias
+    names = _collect_names(tree)
+    if names & _FORBIDDEN_CALLS:
+        raise SecurityError(f"Forbidden builtins present: {', '.join(names & _FORBIDDEN_CALLS)}")

wishful-0.1.0/src/wishful/ui.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from wishful.config import settings
+
+_console = Console()
+
+
+@contextmanager
+def spinner(message: str) -> Iterator[None]:
+    if not settings.spinner:
+        yield
+        return
+
+    with Progress(SpinnerColumn(), TextColumn(message), console=_console, transient=True) as progress:
+        task_id = progress.add_task(message, total=None)
+        try:
+            yield
+        finally:
+            progress.update(task_id, completed=1)
+            progress.stop()