wishful 0.2.1__py3-none-any.whl

wishful/llm/client.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import os
+from typing import Sequence
+
+import litellm
+
+from wishful.config import settings
+from wishful.llm.prompts import build_messages, strip_code_fences
+from wishful.logging import logger
+
+
+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,
+    type_schemas: dict[str, str] | None = None,
+    function_output_types: dict[str, str] | None = None,
+    mode: str | None = None,
+) -> str:
+    """Call the LLM (or fake stub) to generate module source code."""
+
+    if _FAKE_MODE:
+        return _fake_response(functions)
+
+    response = _call_llm(
+        module, functions, context, type_schemas, function_output_types, mode
+    )
+    content = _extract_content(response)
+    return strip_code_fences(content).strip()
+
+
+def _call_llm(
+    module: str,
+    functions: Sequence[str],
+    context: str | None,
+    type_schemas: dict[str, str] | None = None,
+    function_output_types: dict[str, str] | None = None,
+    mode: str | None = None,
+):
+    messages = build_messages(
+        module, functions, context, type_schemas, function_output_types, mode
+    )
+    logger.debug(
+        "LLM call module={} mode={} model={} temp={} max_tokens={} functions={} context_len={} type_schemas={} output_types={} preview={}",
+        module,
+        mode,
+        settings.model,
+        settings.temperature,
+        settings.max_tokens,
+        list(functions),
+        len(context) if context else 0,
+        list((type_schemas or {}).keys()),
+        list((function_output_types or {}).keys()),
+        (context[:500] + "…" if context and len(context) > 500 else (context or "")),
+    )
+
+    # Log the actual prompt messages (truncated for safety)
+    prompt_text = "\n".join(f"{m['role'].upper()}: {m['content']}" for m in messages)
+    if len(prompt_text) > 4000:
+        prompt_text = prompt_text[:4000] + "…"
+    logger.debug("LLM prompt for {}:\n{}", module, prompt_text)
+    try:
+        return 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
+
+
+def _extract_content(response) -> str:
+    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 content

wishful/llm/prompts.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import List, Sequence
+
+from wishful.config import settings
+
+
+def build_messages(
+    module: str,
+    functions: Sequence[str],
+    context: str | None,
+    type_schemas: dict[str, str] | None = None,
+    function_output_types: dict[str, str] | None = None,
+    mode: str | None = None,
+) -> List[dict]:
+    user_parts = [f"Module: {module}"]
+
+    # Include type schemas if available
+    if type_schemas:
+        user_parts.append(
+            "Type definitions to include in the module:\n"
+            "(Copy these type definitions directly into the generated code. "
+            "Do NOT import them from other modules.)\n"
+        )
+        for type_name, schema in type_schemas.items():
+            user_parts.append(f"\n{schema}\n")
+
+    # Include function signatures with output types
+    if functions:
+        if function_output_types:
+            func_list = []
+            for func in functions:
+                if func in function_output_types:
+                    output_type = function_output_types[func]
+                    func_list.append(f"{func}(...) -> {output_type}")
+                else:
+                    func_list.append(func)
+            user_parts.append(
+                "Functions to implement:\n" + "\n".join(f"- {f}" for f in func_list)
+            )
+        else:
+            user_parts.append(f"Functions to implement: {', '.join(functions)}")
+
+    if context:
+        user_parts.append("Context:\n" + context.strip())
+
+    if mode == "dynamic":
+        user_parts.append(
+            "Dynamic mode guidance:\n"
+            "- Treat the call-site context as one-off. Return a single, fully baked result.\n"
+            "- Do NOT build strings with templates, f-strings, or .format; write the final prose directly.\n"
+            "- Use contextual values (like settings, style, length hints) naturally in the narrative instead of inserting them verbatim at the start.\n"
+            "- Keep the function signature, but it's fine if the body ignores parameters after using them as creative guidance."
+        )
+
+    user_prompt = "\n\n".join(user_parts)
+
+    return [
+        {"role": "system", "content": settings.system_prompt},
+        {"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/logging.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from loguru import logger
+from rich.logging import RichHandler
+
+from wishful.config import settings
+
+
+_configured = False
+
+
+def _log_dir() -> Path:
+    return settings.cache_dir / "_logs"
+
+
+def _configure_rich_console(level: str):
+    # Configure a dedicated logger using RichHandler
+    handler = RichHandler(
+        show_time=True,
+        show_level=True,
+        show_path=True,
+        enable_link_path=True,
+        rich_tracebacks=True,
+        markup=True,
+        log_time_format="%H:%M:%S.%f",
+    )
+    handler.setLevel(level)
+
+    import logging
+
+    rich_logger = logging.getLogger("wishful.rich")
+    rich_logger.handlers.clear()
+    rich_logger.propagate = False
+    rich_logger.setLevel(level)
+    rich_logger.addHandler(handler)
+    return rich_logger
+
+
+def configure_logging(force: bool = False) -> None:
+    global _configured
+
+    # Avoid repeated reconfiguration unless forced
+    if _configured and not force:
+        return
+
+    logger.remove()
+
+    level = (settings.log_level or ("DEBUG" if settings.debug else "WARNING")).upper()
+
+    # Console sink: only when debug or level <= INFO
+    # Console via RichHandler for nicer TTY output
+    rich_logger = _configure_rich_console(level)
+    logger.add(
+        lambda m: rich_logger.log(
+            m.record["level"].no,
+            f"{m.record['module']}:{m.record['function']}:{m.record['line']} | {m.record['message']}",
+        ),
+        level=level,
+        enqueue=False,
+        backtrace=False,
+        diagnose=False,
+    )
+
+    if settings.log_to_file:
+        log_dir = _log_dir()
+        log_dir.mkdir(parents=True, exist_ok=True)
+        logfile = log_dir / f"{datetime.now():%Y-%m-%d}.log"
+        logfile.touch(exist_ok=True)
+        logger.add(
+            str(logfile),
+            level=level,
+            enqueue=False,
+            backtrace=False,
+            diagnose=False,
+            rotation=None,
+            retention=None,
+            format="{time:YYYY-MM-DD HH:mm:ss.SSS} | {level} | {message}",
+        )
+
+    _configured = True
+
+
+# Configure once at import time with defaults
+configure_logging()

wishful/safety/__init__.py

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

wishful/safety/validator.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import ast
+from typing import Iterable
+
+
+class SecurityError(ImportError):
+    """Raised when generated code violates safety policy."""
+
+
+_FORBIDDEN_IMPORTS = {"os", "subprocess", "sys"}
+_FORBIDDEN_CALLS = {"eval", "exec"}
+_WRITE_MODES = {"w", "a", "+"}
+
+
+def _parse_source(source: str) -> ast.AST:
+    try:
+        return ast.parse(source)
+    except SyntaxError as exc:
+        raise ImportError(f"Generated code has syntax error: {exc}") from exc
+
+
+def _check_imports(tree: ast.AST) -> None:
+    _validate_import_names(list(_iter_import_names(tree)))
+
+
+def _iter_import_names(tree: ast.AST):
+    yield from _import_names(tree)
+    yield from _importfrom_names(tree)
+
+
+def _import_names(tree: ast.AST):
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                yield alias.name
+
+
+def _importfrom_names(tree: ast.AST):
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module:
+            yield node.module
+
+
+def _validate_import_names(names: Iterable[str]) -> None:
+    for name in names:
+        if name.split(".")[0] in _FORBIDDEN_IMPORTS:
+            raise SecurityError(f"Forbidden import: {name}")
+
+
+def _check_calls(tree: ast.AST) -> None:
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        if isinstance(node.func, ast.Name):
+            _check_named_call(node.func.id, node)
+        elif isinstance(node.func, ast.Attribute):
+            _check_attribute_call(node.func)
+
+
+def _check_named_call(func_name: str, call: ast.Call) -> None:
+    if func_name in _FORBIDDEN_CALLS:
+        raise SecurityError(f"Forbidden call: {func_name}()")
+    if func_name == "open":
+        _validate_open_call(call)
+
+
+def _check_attribute_call(attr: ast.Attribute) -> None:
+    dotted = _resolve_attribute_name(attr)
+    if dotted.startswith("os.") or dotted.startswith("subprocess."):
+        raise SecurityError(f"Forbidden call: {dotted}()")
+
+
+def _resolve_attribute_name(attr: ast.Attribute) -> str:
+    parts = []
+    current: ast.AST | None = attr
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if isinstance(current, ast.Name):
+        parts.append(current.id)
+    return ".".join(reversed(parts))
+
+
+def _validate_open_call(call: ast.Call) -> None:
+    mode_arg = _extract_open_mode(call)
+    if mode_arg and any(ch in mode_arg for ch in _WRITE_MODES):
+        raise SecurityError("open() in write/append mode is blocked")
+
+
+def _extract_open_mode(call: ast.Call) -> str | None:
+    positional = _extract_positional_mode(call)
+    if positional is not None:
+        return positional
+    return _extract_keyword_mode(call)
+
+
+def _extract_positional_mode(call: ast.Call) -> str | None:
+    if len(call.args) > 1 and isinstance(call.args[1], ast.Constant):
+        return str(call.args[1].value)
+    return None
+
+
+def _extract_keyword_mode(call: ast.Call) -> str | None:
+    for kw in call.keywords:
+        if kw.arg == "mode" and isinstance(kw.value, ast.Constant):
+            return str(kw.value.value)
+    return None
+
+
+def _check_forbidden_builtins(tree: ast.AST) -> None:
+    names = {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}
+    forbidden = names & _FORBIDDEN_CALLS
+    if forbidden:
+        joined = ", ".join(sorted(forbidden))
+        raise SecurityError(f"Forbidden builtins present: {joined}")
+
+
+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
+
+    tree = _parse_source(source)
+    _check_imports(tree)
+    _check_calls(tree)
+    _check_forbidden_builtins(tree)

wishful/static/__init__.py

@@ -0,0 +1,8 @@
+"""Wishful static namespace - cached code generation.
+
+Modules imported from wishful.static.* are generated once, cached to disk,
+and reused on subsequent imports for optimal performance.
+
+Example:
+    from wishful.static.text import extract_emails
+"""

wishful/static/__init__.pyi

@@ -0,0 +1,7 @@
+"""Type stub for wishful.static namespace.
+
+This stub helps IDEs and type checkers understand that wishful.static.*
+is a valid namespace for dynamically generated modules.
+"""
+
+def __getattr__(name: str) -> object: ...

wishful/types/__init__.py

@@ -0,0 +1,19 @@
+"""Type registry for complex type hints in wishful."""
+
+from wishful.types.registry import (
+    TypeRegistry,
+    clear_type_registry,
+    get_all_type_schemas,
+    get_output_type_for_function,
+    get_type_schema,
+    type,
+)
+
+__all__ = [
+    "type",
+    "TypeRegistry",
+    "get_type_schema",
+    "get_all_type_schemas",
+    "get_output_type_for_function",
+    "clear_type_registry",
+]