feat: Python task execution and enable/disable controls

CLAUDE.md

@@ -138,7 +138,7 @@ app = (
 - `.with_config(schema)` - Config CRUD endpoints at `/api/v1/configs`
 - `.with_artifacts(hierarchy)` - Artifact CRUD at `/api/v1/artifacts`
 - `.with_jobs()` - Job scheduler at `/api/v1/jobs`
-- `.with_tasks()` - Task execution at `/api/v1/tasks`
+- `.with_tasks(validate_on_startup=True)` - Task execution at `/api/v1/tasks` with automatic Python task validation
 - `.with_ml(runner)` - ML train/predict at `/api/v1/ml`
 - `.with_logging()` - Structured logging with request tracing
 - `.with_auth()` - API key authentication
@@ -255,12 +255,69 @@ apps/
 
 See `examples/app_hosting_api.py` and `examples/apps/sample-dashboard/` for complete working example.
 
+## Task Execution System
+
+Chapkit provides a task execution system supporting both shell commands and Python functions with type-based dependency injection.
+
+**Task Types:**
+- **Shell tasks**: Execute commands via asyncio subprocess, capture stdout/stderr/exit_code
+- **Python tasks**: Execute registered functions via TaskRegistry, capture result/error with traceback
+
+**Python Task Registration:**
+```python
+from chapkit import TaskRegistry
+
+@TaskRegistry.register("my_task")
+async def my_task(name: str, session: AsyncSession) -> dict:
+    """Task with user parameters and dependency injection."""
+    # name comes from task.parameters (user-provided)
+    # session is injected by framework (type-based)
+    return {"status": "success", "name": name}
+```
+
+**Type-Based Dependency Injection:**
+
+Framework types are automatically injected based on function parameter type hints:
+- `AsyncSession` - SQLAlchemy async database session
+- `Database` - Chapkit Database instance
+- `ArtifactManager` - Artifact management service
+- `JobScheduler` - Job scheduling service
+
+**Key Features:**
+- Enable/disable controls for tasks
+- Automatic orphaned task validation (enabled by default, auto-disables tasks with missing functions on startup)
+- Support both sync and async Python functions
+- Mix user parameters with framework injections
+- Optional type support (`AsyncSession | None`)
+- Artifact-based execution results for both shell and Python tasks
+
+**Example:**
+```python
+app = (
+    ServiceBuilder(info=ServiceInfo(display_name="Task Service"))
+    .with_health()
+    .with_artifacts(hierarchy=TASK_HIERARCHY)
+    .with_jobs(max_concurrency=3)
+    .with_tasks()  # Adds task CRUD + execution, validates on startup by default
+    .build()
+)
+
+# Disable validation if needed
+app = (
+    ServiceBuilder(info=info)
+    .with_tasks(validate_on_startup=False)
+    .build()
+)
+```
+
+See `docs/guides/task-execution.md` for complete documentation and `examples/python_task_execution_api.py` for working examples.
+
 ## Common Endpoints
 
 **Config Service:** Health check, CRUD operations, pagination (`?page=1&size=20`), schema endpoint (`/$schema`)
 **Artifact Service:** CRUD + tree operations (`/$tree`), optional config linking
 **Job Scheduler:** List/get/delete jobs, status filtering
-**Task Service:** CRUD + execute operation (`/$execute`)
+**Task Service:** CRUD, execute (`/$execute`), enable/disable controls, Python function registry, type-based injection
 **ML Service:** Train (`/$train`) and predict (`/$predict`) operations
 
 **Operation prefix:** `$` indicates operations (computed/derived data) vs resource access

ROADMAP.md

@@ -1,19 +1,152 @@
+# Chapkit Roadmap
 
-## Core Improvements
+> **Vision:** Build the most productive async Python framework for ML/data services with FastAPI integration
 
-- [ ] Support artifact export (PandasDataFrame => csv/parquet, pandas => csv/json/parquet)
-- [ ] Store more meta information for train/predict runs (full config, type etc)
-- [ ] Support multiple types for /api/configs
+## Priority Legend
+- **High Priority** - Next 1-2 releases (actively working or immediate next)
+- **Medium Priority** - Next 3-6 releases (planned, design in progress)
+- **Future** - Under consideration (evaluate demand/feasibility)
 
-## Type Safety
-- [ ] Stricter generic type constraints
-- [ ] Runtime type validation options
-- [ ] Better inference for generic managers
-- [ ] Type-safe configuration builder
+---
 
-## Code Quality
-- [ ] Performance benchmarking suite
-- [ ] Memory leak detection
-- [ ] Code coverage improvements (target 95%+)
-- [ ] Dependency injection improvements
-- [ ] Create chapkit.client.Client for testing/working with instances
+## High Priority (Next 1-2 Releases)
+
+### Task Execution
+- [ ] **Task scheduling (Phase 2)** - Cron, interval, and one-off scheduling with in-memory storage
+  - Already designed in `designs/python-tasks-and-scheduling.md`
+  - Background scheduler worker
+  - Schedule enable/disable controls
+  - Migration path to persistent scheduling
+
+- [ ] **Decorator-based ML runner registration** - Extend TaskRegistry with metadata
+  - Reuse TaskRegistry instead of creating new registry
+  - `@TaskRegistry.register("model_name", type="ml_train")`
+  - `FunctionalModelRunner.from_registry()` factory method
+  - Cleaner API, consistent with task patterns
+
+### Developer Experience
+- [ ] **chapkit.client.Client** - Python client for testing and working with chapkit services
+  - Type-safe client with IDE support
+  - Automatic serialization/deserialization
+  - Request/response validation
+  - Essential for testing and SDK users
+
+### Artifact System
+- [ ] **Artifact export** - Export DataFrames and data structures from artifacts
+  - CSV, Parquet, JSON formats
+  - Streaming for large datasets
+  - Compression support (gzip, bzip2)
+
+---
+
+## Medium Priority (Next 3-6 Releases)
+
+### Task Execution Enhancements
+- [ ] **Retry policies** - Automatic retry with exponential backoff for failed tasks
+- [ ] **Custom injectable types** - User-defined dependency injection types
+- [ ] **Result caching** - Cache task results based on parameters with TTL
+
+### ML System
+- [ ] **Enhanced train/predict metadata** - Store full config, model type, framework version, hyperparameters
+- [ ] **Model versioning** - Track model lineage and version history
+- [ ] **Experiment tracking** - MLflow or W&B integration for experiment management
+
+### Configuration
+- [ ] **Multiple config types** - Support multiple config schemas per service
+- [ ] **Config versioning** - Track and rollback config changes
+
+### Observability
+- [ ] **Distributed tracing** - OpenTelemetry integration for request tracing
+- [ ] **Enhanced metrics** - Custom metrics registration and SLO tracking
+- [ ] **Structured audit logging** - Comprehensive audit trails for compliance
+
+### Type Safety
+- [ ] **Stricter generic constraints** - Better compile-time type checking
+- [ ] **Runtime type validation** - Optional runtime validation layer
+
+---
+
+## Future Considerations
+
+### Advanced Task Features
+- [ ] **Registry namespacing** - Module-scoped registries to avoid collisions
+- [ ] **Function versioning** - Track function versions in artifacts
+- [ ] **Parameter serialization** - Custom serializers for complex types
+
+### ML Advanced Features
+- [ ] **Model registry** - Central registry for discovering trained models
+- [ ] **A/B testing** - Deploy multiple model versions with traffic splitting
+- [ ] **Pipeline composition** - Chain models and transformations
+- [ ] **Feature store integration** - Connect to feature stores
+
+### Developer Tools
+- [ ] **CLI tool** - Command-line tool for migrations, seeding, testing
+- [ ] **Code generation** - Generate boilerplate for modules, routers, models
+- [ ] **Development server** - Enhanced dev server with auto-reload
+
+### Testing & Quality
+- [ ] **Performance benchmarking** - Comprehensive benchmarks for core operations
+- [ ] **Memory leak detection** - Automated leak detection in tests
+- [ ] **Code coverage 95%+** - Target high coverage across all modules
+- [ ] **Load testing tools** - Built-in load testing utilities
+
+### API & Middleware
+- [ ] **WebSocket support** - Real-time updates via WebSockets
+- [ ] **Rate limiting** - Built-in rate limiting middleware
+- [ ] **Response caching** - Intelligent caching layer
+- [ ] **GraphQL support** - Optional GraphQL layer (evaluate demand first)
+- [ ] **gRPC support** - High-performance gRPC endpoints (evaluate demand first)
+
+### Security
+- [ ] **RBAC** - Role-based access control
+- [ ] **OAuth2/JWT** - Modern authentication flows
+- [ ] **Encryption at rest** - Encrypt sensitive artifacts and configs
+- [ ] **Secret management** - Vault, AWS Secrets Manager integration
+
+### Cloud & Storage
+- [ ] **Artifact cloud storage** - S3, GCS, Azure Blob backends
+- [ ] **PostgreSQL adapter** - Production-grade relational DB support
+- [ ] **Message queue integration** - RabbitMQ, Kafka for async processing
+
+### Documentation
+- [ ] **Tutorial series** - Step-by-step guides for common patterns
+- [ ] **Architecture guide** - Deep dive into chapkit internals
+- [ ] **Best practices** - Production deployment patterns
+- [ ] **Video tutorials** - Screencast series for key features
+
+---
+
+## Recently Completed
+
+### v0.x (Current)
+- **Python task execution** - TaskRegistry with decorator-based registration
+- **Type-based dependency injection** - Automatic injection of framework services
+- **Enable/disable controls** - Task execution controls
+- **Orphaned task validation** - Auto-disable tasks with missing functions
+- **App hosting system** - Host static web apps alongside API
+- **Health check SSE streaming** - Server-sent events for health monitoring
+- **Comprehensive testing** - 683 tests passing with extensive coverage
+- **ML service builder** - Specialized builder for ML workflows
+
+---
+
+## Evaluation Criteria for New Features
+
+Before adding items to this roadmap, consider:
+
+1. **Core Value Alignment** - Does it enhance ML/data service development?
+2. **Developer Experience** - Does it reduce boilerplate or improve productivity?
+3. **Production Readiness** - Does it solve real production challenges?
+4. **Maintenance Burden** - Can we maintain it long-term?
+5. **Community Demand** - Are users asking for it?
+6. **Breaking Changes** - Can we add it without breaking existing code?
+
+## Contributing
+
+Have ideas for the roadmap? Open an issue with:
+- **Use case** - What problem does it solve?
+- **Alternatives** - What workarounds exist today?
+- **Impact** - How many users would benefit?
+- **Effort** - Rough complexity estimate
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.

alembic/versions/20251010_0927_4d869b5fb06e_initial_schema.py

@@ -1,10 +1,4 @@
-"""initial_schema
-
-Revision ID: 4d869b5fb06e
-Revises:
-Create Date: 2025-10-10 09:27:01.866482+00:00
-
-"""
+"""Initial database schema migration."""
 
 import sqlalchemy as sa
 
@@ -57,6 +51,9 @@ def upgrade() -> None:
     op.create_table(
         "tasks",
         sa.Column("command", sa.Text(), nullable=False),
+        sa.Column("task_type", sa.Text(), nullable=False, server_default="shell"),
+        sa.Column("parameters", sa.JSON(), nullable=True),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default="1"),
         sa.Column("id", chapkit.core.types.ULIDType(length=26), nullable=False),
         sa.Column("created_at", sa.DateTime(), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
         sa.Column("updated_at", sa.DateTime(), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),