{"id":30807678,"url":"https://github.com/robotdad/shadow-cauldron","last_synced_at":"2025-10-18T20:33:33.998Z","repository":{"id":311529247,"uuid":"1043941996","full_name":"robotdad/shadow-cauldron","owner":"robotdad","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-25T01:17:03.000Z","size":271,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-25T04:25:13.568Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robotdad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-25T00:01:40.000Z","updated_at":"2025-08-25T01:17:06.000Z","dependencies_parsed_at":"2025-08-25T04:25:43.858Z","dependency_job_id":"60936079-44fa-408b-8e97-2e0279c5c9d3","html_url":"https://github.com/robotdad/shadow-cauldron","commit_stats":null,"previous_names":["robotdad/shadow-cauldron"],"tags_count":null,"template":false,"template_full_name":"bkrabach/ai-code-project-template","purl":"pkg:github/robotdad/shadow-cauldron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Fshadow-cauldron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Fshadow-cauldron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Fshadow-cauldron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Fshadow-cauldron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robotdad","download_url":"https://codeload.github.com/robotdad/shadow-cauldron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robotdad%2Fshadow-cauldron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273850877,"owners_count":25179357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T02:49:06.514Z","updated_at":"2025-10-18T20:33:28.980Z","avatar_url":"https://github.com/robotdad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shadow Cauldron - AI Experimentation Platform\n\n## Purpose\n\nShadow Cauldron is a modular AI experimentation platform that enables parallel testing and comparison of different AI providers and models. Built following the \"bricks and studs\" philosophy, it provides a structured way to design, execute, and analyze AI experiments.\n\n## Architecture\n\nThis application is built as a collection of self-contained \"bricks\" that communicate through well-defined contracts:\n\n```\nshadow-cauldron/\n├── app/                        # Main application\n│   ├── config/                # Configuration brick\n│   ├── core/                  # Auth, middleware, logging brick\n│   ├── api/                   # API routes brick\n│   ├── models/                # Database models brick\n│   ├── providers/             # AI provider plugin system brick\n│   ├── experiments/           # Experiment engine brick\n│   └── storage/               # File \u0026 data management brick\n├── tests/                     # Test suite\n├── docker/                    # Container configurations\n└── alembic/                   # Database migrations\n```\n\n## Modular Design Principles\n\nEach brick follows these principles:\n\n1. **Single Responsibility**: Each brick has one clear purpose\n2. **Contract-Based**: Public interfaces defined in `__init__.py`\n3. **Self-Contained**: All code, tests, and dependencies within brick folder\n4. **Regeneratable**: Can be rebuilt from specification without breaking connections\n5. **Minimal Dependencies**: Bricks connect only through public contracts\n\n## Public Contracts\n\n### Config Brick\n```python\nfrom app.config import settings, Settings, DatabaseConfig\n```\n\n### Core Brick  \n```python\nfrom app.core import setup_logging, setup_middleware, get_current_user, AuthenticatedUser\n```\n\n### API Brick\n```python\nfrom app.api import router\n```\n\n### Models Brick\n```python\nfrom app.models import Base, SessionLocal, get_db, User\n```\n\n### Providers Brick\n```python\nfrom app.providers import ProviderRegistry, BaseProvider, get_provider, list_providers\n```\n\n### Experiments Brick\n```python\nfrom app.experiments import ExperimentEngine, Experiment, ExperimentRun, create_experiment, run_experiment\n```\n\n### Storage Brick\n```python\nfrom app.storage import StorageManager, upload_file, get_file, delete_file\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Python 3.11+\n- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python package manager)\n- Git\n\n**Note**: This project uses SQLite by default for development (no additional database setup required). PostgreSQL can be used for production.\n\n### Quick Start\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/robotdad/shadow-cauldron.git\ncd shadow-cauldron\n\n# 2. Install dependencies (creates .venv automatically)\nmake install\n\n# 3. Set up environment (optional for development)\ncp .env.example .env\n# Edit .env if you need custom settings\n\n# 4. Initialize database\nmake migrate\n\n# 5. Start development server\nmake dev\n```\n\nThe application will be available at: **http://localhost:8000**\n\n- Health check: http://localhost:8000/health\n- API status: http://localhost:8000/api/v1/status  \n- API docs: http://localhost:8000/docs (in debug mode)\n\n### Verify Installation\n\n```bash\n# Check health endpoint\ncurl http://localhost:8000/health\n# Should return: {\"status\":\"healthy\",\"service\":\"shadow-cauldron\"}\n\n# Run tests\nmake test\n# Should show: 3 passed\n\n# Check code quality\nmake check\n# Should format and lint code successfully\n```\n\n### Environment Variables (Optional)\n\nThe application works out of the box with sensible defaults. Environment variables are prefixed with `SC_`:\n\n**Required for production:**\n- `SC_SECRET_KEY`: Secret key for JWT tokens (defaults to dev key)\n\n**Optional:**\n- `SC_DATABASE_URL`: Database connection URL (defaults to SQLite: `sqlite+aiosqlite:///./shadow_cauldron.db`)\n- `SC_DEBUG`: Enable debug mode (defaults to `false`)\n- `SC_HOST`: Server host (defaults to `0.0.0.0`)\n- `SC_PORT`: Server port (defaults to `8000`)\n- `SC_OPENAI_API_KEY`: OpenAI API key for AI providers\n- `SC_ANTHROPIC_API_KEY`: Anthropic API key for AI providers\n\n**Example `.env` file:**\n```bash\nSC_DEBUG=true\nSC_SECRET_KEY=your-secure-secret-key-here\nSC_OPENAI_API_KEY=your-openai-key\nSC_ANTHROPIC_API_KEY=your-anthropic-key\n```\n\n### Development\n\n```bash\n# Run all checks (lint, format, type check)\nmake check\n\n# Run tests\nmake test\n\n# Start development server with hot reload\nmake dev\n\n# Create database migration\nmake revision MSG=\"Add new table\"\n\n# Apply migrations\nmake migrate\n```\n\n### Troubleshooting\n\n**Common Issues:**\n\n1. **`uv` not found**: Install uv from https://docs.astral.sh/uv/getting-started/installation/\n2. **Permission errors**: Make sure you have write permissions in the project directory\n3. **Port 8000 in use**: Either stop the service using port 8000 or set `SC_PORT=8001` in your `.env`\n4. **Database errors**: Run `make reset-db` to recreate the database from scratch\n\n**Getting Help:**\n- Check the logs when running `make dev`\n- Verify all tests pass with `make test`\n- Ensure code quality with `make check`\n\n## API Endpoints\n\n- `GET /health` - Health check\n- `GET /api/v1/status` - API status\n- `GET /api/v1/protected` - Protected endpoint (requires authentication)\n- `GET /api/v1/experiments` - List experiments\n- `GET /api/v1/providers` - List AI providers\n\n## Key Features\n\n### Multi-Provider Support\n- Plugin-based AI provider system\n- Support for OpenAI, Anthropic, and custom providers\n- Unified interface for all providers\n\n### Parallel Experimentation\n- Run experiments across multiple providers simultaneously\n- Compare results, performance, and costs\n- Structured experiment configuration\n\n### Storage Management\n- File upload and management\n- Experiment data persistence\n- Result archiving and retrieval\n\n### Authentication \u0026 Security\n- JWT-based authentication\n- Role-based access control\n- Secure API key management\n\n## Extension Points\n\nTo add new functionality:\n\n1. **New Provider**: Implement `BaseProvider` in `app/providers/`\n2. **New API Routes**: Add routes in `app/api/routes.py`\n3. **New Models**: Add SQLAlchemy models in `app/models/`\n4. **New Storage Backend**: Extend `StorageManager` in `app/storage/`\n\n## Testing\n\nThe project includes comprehensive testing at multiple levels:\n\n- **Unit Tests**: Test individual brick functionality\n- **Integration Tests**: Test brick interactions\n- **End-to-End Tests**: Test complete user workflows\n\n## Contributing\n\nWhen modifying the codebase:\n\n1. Each brick should remain self-contained\n2. Changes to public contracts require updating dependent bricks\n3. Prefer regenerating entire bricks over line-by-line edits\n4. Add tests for new functionality\n5. Update documentation for contract changes\n\n## Current Status\n\n**Phase 1: Foundation ✅ Complete**\n- ✅ Modular architecture with 7 self-contained bricks\n- ✅ FastAPI backend with JWT authentication\n- ✅ SQLite database with migrations\n- ✅ Provider plugin system foundation\n- ✅ Experiment orchestration framework  \n- ✅ Development tools and testing\n\n**Phase 2: AI Provider Integration (Planned)**\n- 🔄 HuggingFace Diffusers integration\n- 🔄 OpenAI and Anthropic providers\n- 🔄 RTX 4080 GPU optimizations\n- 🔄 Parallel experiment execution\n\n## Contributing\n\nContributions are welcome! When modifying the codebase:\n\n1. Each brick should remain self-contained\n2. Changes to public contracts require updating dependent bricks  \n3. Prefer regenerating entire bricks over line-by-line edits\n4. Add tests for new functionality\n5. Update documentation for contract changes\n\n## License\n\nMIT License - see LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotdad%2Fshadow-cauldron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobotdad%2Fshadow-cauldron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotdad%2Fshadow-cauldron/lists"}