feat: Dynamic improvements, logging, and comprehensive documentation

[pyros-projects]

🚀 Summary

This PR introduces major enhancements to wishful's dynamic generation capabilities, comprehensive logging infrastructure, and improved documentation. The changes significantly improve the runtime-aware regeneration system, add production-grade logging, and enhance the developer experience.

---

✨ Key Features

📝 Logging Infrastructure (NEW)

• Integrated loguru with Rich console output for beautiful, readable logs
• File-based logging with daily rotation in .wishful/_logs/
• Configurable log levels via wishful.configure(log_level="DEBUG") or WISHFUL_LOG_LEVEL env var
• Automatic debug mode defaults: debug=True enables DEBUG level, file logging, and disables spinners
• Comprehensive tracing throughout import flow: cache hits/misses, generation, execution, syntax retries
• LLM call logging: Full visibility into prompts, models, tokens, and responses

🔄 Dynamic Namespace Enhancements

• Runtime context injection: wishful.dynamic.* modules now receive call-site context (function name, args, kwargs)
• Dynamic proxy module: Each attribute access triggers regeneration with runtime awareness
• Call-time regeneration: Functions regenerate before execution with actual parameter values
• Snapshot system: Dynamic generations are saved to .wishful/_snapshots/ for debugging
• Improved prompts for dynamic mode: Special guidance tells LLM to generate "baked" content, not templates

🐛 Error Handling & Resilience

• Syntax error recovery: Automatic retry on SyntaxError (one attempt) with cache invalidation
• Improved loader state management: Preserves _wishful_loader across module reloads
• Better logging on failures: Clear warnings and debug traces for troubleshooting

🛡️ Finder & Module System Improvements

• Idempotent finder installation: More robust check prevents duplicate finders
• Root namespace handling: Proper delegation to installed package for wishful root
• Module cleanup: Test infrastructure now preserves internal modules during cleanup

📖 Documentation & Examples

• AGENTS.md fully synced with current codebase state
• New examples:
  • 10_cosmic_horror_line_by_line.py - demonstrates dynamic runtime context
  • 11_logging.py - showcases logging configuration
• Astro documentation site foundation in docs-site/
• Comprehensive test coverage with new logging tests

---

📊 Changes by Category

Core System ()

New Files

• src/wishful/logging.py - Complete logging infrastructure with loguru + Rich

Modified Files

config.py

• Added log_level and log_to_file settings
• configure() now accepts log_level and log_to_file parameters
• Automatic debug mode defaults: debug=True → log_level="DEBUG", log_to_file=True, spinner=False
• Lazy logging module import to avoid circular dependencies
• reset_defaults() now reconfigures logging

core/discovery.py

• Runtime context support: New runtime_context parameter in discover()
• _append_runtime_context() helper to format runtime call info for LLM
• _is_plain_import() detects module-level imports (vs from-imports)
• Fallback context capture: Even without explicit symbols, captures nearby code
• Improved type schema and output type integration

core/finder.py

• Root namespace delegation: Returns None for bare wishful to let package handle it
• Robust duplicate detection: Uses class name + module check for idempotent installation
• Uses sys directly instead of __import__("sys")

core/loader.py

• DynamicProxyModule class: New proxy that regenerates on each attribute access
• _resolve_generate_module_code(): Function resolver that respects monkeypatches
• mode parameter propagated through generation pipeline
• _regenerate_for_proxy(): Handles attribute access regeneration
• _call_with_runtime(): Captures args/kwargs and regenerates with runtime context
• Syntax error retry logic: One automatic retry with cache invalidation
• Dynamic snapshot writing: cache.write_dynamic_snapshot() for debug traces
• Comprehensive logging at every stage: exec, generation, cache hits/misses, errors
• file_path tracking: Proper __file__ attribution for generated modules

llm/client.py

• mode parameter added to generate_module_code() and _call_llm()
• Extensive debug logging: Model, tokens, temperature, functions, context preview
• Prompt logging: Full messages logged (truncated for safety)

llm/prompts.py

• Dynamic mode guidance: Special instructions for mode="dynamic"
  • "Return a single, fully baked result"
  • "Do NOT build strings with templates"
  • "Use contextual values naturally in the narrative"

cache/manager.py

• write_dynamic_snapshot() and dynamic_snapshot_path() for dynamic mode tracing

Tests ()

conftest.py

• Default debug mode: Tests now run with debug=True for full logging
• Improved module cleanup: Preserves internal wishful.* modules, only clears static/dynamic

test_import_hook.py

• test_dynamic_call_includes_runtime_context() - verifies runtime context injection
• test_static_syntax_error_retries_once() - validates retry logic for static
• test_dynamic_syntax_error_retries_once() - validates retry logic for dynamic
• test_dynamic_writes_snapshot() - confirms snapshot creation

test_logging.py (NEW)

• test_logging_creates_file_and_records_generation() - file logging verification
• test_logging_records_syntax_retry() - retry event logging

test_namespaces.py

• Updated test_dynamic_skips_cache() to expect multiple calls (import + proxy)
• test_dynamic_proxy_regenerates_on_each_access() - proxy behavior validation

Examples

• 10_cosmic_horror_line_by_line.py - Creative writing with runtime context
• 11_logging.py - Logging configuration showcase

Documentation

• AGENTS.md: Comprehensive update with logging, dynamic improvements, TDD process
• README.md: Updated (implied by commit history)
• docs-site/: New Astro documentation site foundation

Dependencies

• Added loguru>=0.7.3 to runtime dependencies

---

🧪 Testing

• All existing tests pass with new logging infrastructure
• 5 new tests covering:
  • Runtime context injection
  • Syntax error retry (static + dynamic)
  • Dynamic snapshot creation
  • Logging file creation and content
• Debug mode by default in tests for better visibility

---

🔧 Breaking Changes

None!

This PR is backward compatible. Existing code continues to work:

• wishful.static.* imports behave identically
• Default settings unchanged (logging only activates with debug=True or explicit config)
• Cache structure remains the same

---

📋 Migration Guide

No migration needed! To opt into new features:

Enable Logging

import wishful

# Quick debug mode (enables DEBUG logs + file logging)
wishful.configure(debug=True)

# Or fine-grained control
wishful.configure(log_level="INFO", log_to_file=True)

Use Dynamic Runtime Context

# Old: static generation
from wishful.static.story import generate_scene

# New: runtime-aware regeneration
from wishful.dynamic.story import generate_scene

# Each call regenerates with runtime args as context!
scene1 = generate_scene(mood="grim", length="short")
scene2 = generate_scene(mood="whimsical", length="epic")

---

🎯 Next Steps (Future Work)

• Document logging configuration in main docs
• Add more dynamic examples to showcase runtime context
• Consider structured logging output formats (JSON)
• Explore log aggregation/analysis tools
• Performance profiling with logging overhead measurement

---

📸 Example Output

With wishful.configure(debug=True):

10:15:42.123 | DEBUG | cache miss fullname=wishful.static.text
10:15:42.124 | INFO  | Generating wishful.static.text
10:15:42.125 | DEBUG | LLM call module=wishful.static.text mode=static model=azure/gpt-4.1 ...
10:15:43.456 | DEBUG | generate done fullname=wishful.static.text path=.wishful/text.py
10:15:43.457 | DEBUG | exec_module fullname=wishful.static.text mode=static from_cache=False ...

Logs are also written to .wishful/_logs/2024-11-24.log with daily rotation.

---

🙏 Review Notes

This is a substantial PR but maintains clean separation of concerns:

1. Logging layer is independent and optional
2. Dynamic improvements build on existing architecture
3. Error handling adds resilience without changing happy paths
4. Tests validate all new behaviors

Please review:

• Logging configuration ergonomics
• Dynamic proxy module implementation
• Syntax error retry logic
• Documentation completeness

---

*Ready to merge/home/ai/projects/wishful && git fetch origin main && git status All tests passing, no breaking changes, comprehensive documentation.