Correct the artifact implementation to match Unsandbox API:
- Request parameter: return_artifact (boolean, singular)
- Response field: artifacts (array, plural)
- Data field: content_base64 (not data/content)
Changes:
- Backend: Changed artifacts to return_artifact in request body
- Frontend: Use return_artifact in execute request
- Frontend: Look for artifacts array in response (not artifact singleton)
- Frontend: Decode content_base64 field (not data/content)
- Frontend: Use filename field (primary) over name
- Remove debug console.log statements
- Update CLAUDE.md with correct API contract
The API parameter is singular but response is plural - this is intentional
design by Unsandbox API. Request enables artifact collection, response
returns array of generated artifacts.
Artifacts are returned as base64-encoded data directly in the job response
payload, not as URLs. Previous implementation incorrectly tried to fetch
artifacts from URLs via a proxy endpoint.
Changes:
- Remove /api/code/artifacts proxy endpoint (not needed)
- Update downloadArtifact() to decode base64 and trigger download
- Update viewArtifact() to decode base64 and display inline:
* Images: rendered as data URLs (data:image/png;base64,...)
* Videos: decoded to blob URLs with controls
* Text: decoded and displayed in <pre> blocks
- Update CLAUDE.md with correct artifact format and implementation details
- Add artifact response format example showing base64 data structure
Artifact format in response:
{
"artifacts": [{
"name": "output.png",
"type": "image/png",
"data": "base64string...",
"size": 12345
}]
}
Extract infrastructure/proxy debugging information from CLAUDE.md
into unturf-debugging.md to avoid exposing internal network details.
- Created unturf-debugging.md with full proxy chain documentation
- Added unturf-debugging.md to .gitignore
- Simplified CLAUDE.md to reference debugging doc
- Documented Caddy configuration (not nginx)
- Included troubleshooting steps for 502 errors
This keeps sensitive infrastructure details out of the public repo
while maintaining documentation for internal debugging.
- Update CODE_EXEC_URL from code.ai.unturf.com to api.unsandbox.com
- Fix response field handling for Unsandbox API format (flat structure)
- Add exit code display with color coding (green=0, red=error)
- Update displayExecutionResults to handle stdout/stderr/exit_code at top level
- Simplify error handling for timeout/cancelled jobs
- Add comprehensive Unsandbox API documentation to CLAUDE.md
Add comprehensive v2.0 features to enhance activity creation:
Features Implemented:
- Template variables: {{metadata.key}}, {{current_attempt}}, etc.
- Conditional content blocks: show_if conditions for dynamic content
- Advanced metadata conditions: gte, lt, contains, regex, exists operators
- Conditional navigation: if/elif/else branching based on metadata
- Progressive hints system: Auto-display hints based on attempt number
- Weighted random selection: Probabilistic outcomes with custom weights
- Dynamic question text: Questions with template variables
- Built-in attempt counters: Access to current_attempt, max_attempts, attempts_remaining
Files Modified:
- activity.py: Integrated all v2.0 features into activity execution
- activity_utils.py: New utility module for templates and conditions
- activity_yaml_validator.py: Updated validator for v2.0 schema
- CLAUDE.md: Added session persistence and Twitch Plays model docs
- research/SPEC.yaml: Comprehensive v2.0 feature documentation
Added:
- research/activity-test-v2-features.yaml: Test activity demonstrating all features
All changes validated and tested. Zero errors in validator.
Added mandatory validation step to activity creation workflow:
1. Read research/SPEC.yaml first (fresh spec)
2. Validate with activity_yaml_validator.py after changes
3. All YAMLs must pass validation (0 errors) before committing
Ensures quality and prevents broken activity files from entering the repo.
PROBLEM: activity37 was showing complete code examples in Python, JavaScript,
Java, and C++ BEFORE asking students to write code themselves. This turns
learning into copy-paste practice.
FIXED:
- Hello World section: Removed multi-language code examples from content_blocks
- Variables section: Removed multi-language code examples from content_blocks
- Now explains CONCEPTS (what, why, how languages differ) without showing syntax
- Code examples remain in AI feedback for when students struggle or ask for help
PEDAGOGICAL APPROACH:
1. Explain the concept (stdout, variables, etc.)
2. Explain language differences conceptually (dynamic vs static typing)
3. Ask students to TRY writing code in THEIR language
4. Provide language-specific examples in AI FEEDBACK if they struggle
This way students actually have to THINK and LEARN, not just copy.
UPDATED CLAUDE.md:
- Added new pitfall: "Showing answers before questions"
- Guidance: Explain concepts in content_blocks, provide code examples in ai_feedback
Still validates perfectly with zero errors/warnings.
This guide empowers agents to create activities that validate properly,
are fun and engaging, and terminate correctly.
Key additions:
- Core activity structure with detailed examples
- Critical validation requirements checklist
- Four termination patterns with code examples
- Ten engagement techniques from successful activities
- Best practices for activity development
- Common pitfalls table with fixes
- Complete development workflow
- Quick reference for essential fields
- Minimal working activity example
References activity26-magic-8-ball.yaml, activity31-scientific-method.yaml,
and activity37-programming-languages.yaml as exemplary activities.
Critical fix for guarded_ai.py:
- Add MODEL_NAME_{n} environment variable support
- Fixes hard-coded "model" string that breaks Azure OpenAI and other endpoints
- Falls back to "model" if MODEL_NAME_{n} not specified
- Some endpoints require actual deployment name in model parameter
Validator improvement:
- Allow feedback_prompts as alternative to feedback_tokens_for_ai
- Prevents false warning when using metadata_feedback_filter with new prompt system
Documentation:
- Added MODEL_NAME_{n} examples to CLAUDE.md
- Documented that Azure and similar endpoints need this variable
All 8 activities validated: 0 errors, 0 warnings
Added comprehensive Activity YAML Schema section covering:
- Model Configuration feature (classifier_model and feedback_model)
- Why separate models (speed, quality, cost, flexibility)
- Model defaults (MODEL_1/Hermes as universal default)
- Recommended model combinations table
- Environment variable configuration
- Example programming activity with dual models
- Activity YAML validation instructions
- CLI testing with model configuration
- Qwen3-Coder-30B setup guide (llama.cpp and ollama)
This documents the new dual-model architecture that allows:
- Fast classification with Hermes (8B)
- Specialized feedback with domain models (e.g., Qwen3-Coder 30B)
- Activity and step-level model overrides
Major improvements to battleship game feedback accuracy and user experience:
## New Multi-Prompt Feedback System
- Replaced single feedback with 3 specialized prompts: Shot Report, Ship Status, Game Over
- Each prompt has individual metadata filtering to see only relevant data
- Shot Report only sees hit/miss data, Ship Status only sees ship destruction data
- Added STFU token system to suppress empty messages (filtered out automatically)
## Technical Implementation
- Added per-prompt metadata_filter support in YAML structure
- Updated app.py and guarded_ai.py to handle prompt-specific filtering
- Legacy single-prompt system still works with transition-level filtering
- Added comprehensive test suite for feedback system validation
## User Experience Fixes
- Fixed TTS queue blocking JavaScript execution (async promises instead of await)
- Ship Status now correctly reports who destroyed which ship (role confusion fixed)
- Game Over only appears when game actually ends (no more random messages)
- Maintained dramatic storytelling while ensuring factual accuracy
## Battleship-Specific Improvements
- Ship destruction messages only appear when ships actually sink
- Clear separation of concerns: hits/misses vs ship destruction vs game over
- Eliminated false positive ship destruction reports
- Fixed role reversal where wrong player got credit for destruction
The battleship narrator now provides accurate, contextual feedback while preserving the dramatic naval warfare atmosphere.
- Add comprehensive testing framework with 67 test cases covering unit, integration, and functional testing
- Create universal YAML validator supporting all activity types with validation for metadata operations, terminal steps, and Python syntax
- Implement proper Makefile with venv management and test runners following unDRY principles for copy-paste engineering
- Add requirements-test.txt for test dependencies separation
- Configure pytest with conftest.py for proper environment variable management
- Update CLAUDE.md with Makefile best practices
- All 67 tests passing with proper mocking of external dependencies
Testing coverage includes:
• Unit tests (37): Core app functions, utilities, navigation, response handling
• Integration tests (20): Complete activity workflows and error handling
• Functional tests (9): Full battleship game scenarios and edge cases
• YAML validator (17): Universal validation for all activity configurations
- Add matplotlib.use("Agg") backend configuration to prevent runtime errors in headless environments
- Add error handling guards for script results that might return None
- Fix AI targeting logic to exclude already-fired cells in super hunter and hunter modes
- Update CLAUDE.md with matplotlib best practices
