# Chapkit
[](https://github.com/dhis2-chap/chapkit/actions/workflows/ci.yml)
[](https://codecov.io/gh/dhis2-chap/chapkit)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://dhis2-chap.github.io/chapkit/)
> ML service modules built on servicekit - config, artifact, task, and ML workflows
Chapkit provides domain-specific modules for building machine learning services on top of servicekit's core framework. Includes artifact storage, task execution, configuration management, and ML train/predict workflows.
## Features
- **Artifact Module**: Hierarchical storage for models, data, and experiment tracking with parent-child relationships
- **Task Module**: Reusable command templates for shell and Python task execution with parameter injection
- **Config Module**: Key-value configuration with JSON data and Pydantic validation
- **ML Module**: Train/predict workflows with artifact-based model storage and timing metadata
- **Config-Artifact Linking**: Connect configurations to artifact hierarchies for experiment tracking
## Installation
Using uv (recommended):
```bash
uv add chapkit
```
Or using pip:
```bash
pip install chapkit
```
Chapkit automatically installs servicekit as a dependency.
## CLI Usage
Quickly scaffold a new ML service project using `uvx`:
```bash
uvx chapkit init <project-name>
```
Example:
```bash
uvx chapkit init my-ml-service
```
Options:
- `--path <directory>` - Target directory (default: current directory)
- `--monitoring` - Include Prometheus and Grafana monitoring stack
This creates a ready-to-run ML service with configuration, artifacts, and ML endpoints pre-configured.
## Quick Start
```python
from chapkit import ArtifactHierarchy, BaseConfig
from chapkit.api import ServiceBuilder, ServiceInfo
class MyConfig(BaseConfig):
model_name: str
threshold: float
app = (
ServiceBuilder(info=ServiceInfo(display_name="ML Service"))
.with_health()
.with_config(MyConfig)
.with_artifacts(hierarchy=ArtifactHierarchy(name="ml", level_labels={0: "model"}))
.with_jobs()
.build()
)
```
## Modules
### Config
Key-value configuration storage with Pydantic schema validation:
```python
from chapkit import BaseConfig, ConfigManager
class AppConfig(BaseConfig):
api_url: str
timeout: int = 30
# Automatic validation and CRUD endpoints
app.with_config(AppConfig)
```
### Artifacts
Hierarchical storage for models, data, and experiment tracking:
```python
from chapkit import ArtifactHierarchy, ArtifactManager, ArtifactIn
hierarchy = ArtifactHierarchy(
name="ml_pipeline",
level_labels={0: "experiment", 1: "model", 2: "evaluation"}
)
# Store pandas DataFrames, models, any Python object
artifact = await artifact_manager.save(
ArtifactIn(data=trained_model, parent_id=experiment_id)
)
```
### ML
Train and predict workflows with automatic model storage:
```python
from chapkit.ml import FunctionalModelRunner
import pandas as pd
async def train_model(config: MyConfig, data: pd.DataFrame, geo=None):
"""Train your model - returns trained model object."""
from sklearn.linear_model import LinearRegression
model = LinearRegression()
model.fit(data[["feature1", "feature2"]], data["target"])
return model
async def predict(config: MyConfig, model, historic: pd.DataFrame, future: pd.DataFrame, geo=None):
"""Make predictions - returns DataFrame with predictions."""
predictions = model.predict(future[["feature1", "feature2"]])
future["predictions"] = predictions
return future
# Wrap functions in runner
runner = FunctionalModelRunner(on_train=train_model, on_predict=predict)
app.with_ml(runner=runner)
```
## Architecture
```
chapkit/
├── config/ # Configuration management with Pydantic validation
├── artifact/ # Hierarchical storage for models and data
├── task/ # Reusable task templates (Python functions, shell commands)
├── ml/ # ML train/predict workflows
├── cli/ # CLI scaffolding tools
├── scheduler.py # Job scheduling integration
└── api/ # ServiceBuilder with ML integration
└── service_builder.py # .with_config(), .with_artifacts(), .with_ml()
```
Chapkit extends servicekit's `BaseServiceBuilder` with ML-specific features and domain modules for configuration, artifacts, tasks, and ML workflows.
## Examples
See the `examples/` directory for complete working examples:
- `quickstart/` - Complete ML service with config, artifacts, and ML endpoints
- `config_artifact/` - Config with artifact linking
- `ml_functional/`, `ml_class/`, `ml_shell/` - ML workflow patterns (functional, class-based, shell-based)
- `ml_pipeline/` - Multi-stage ML pipeline with hierarchical artifacts
- `artifact/` - Read-only artifact API with hierarchical storage
- `task_execution/` - Task execution with Python functions and shell commands
- `full_featured/` - Comprehensive example with monitoring, custom routers, and hooks
- `library_usage/` - Using chapkit as a library with custom models
- `custom_migrations/` - Database migrations with custom models
## Documentation
See `docs/guides/` for comprehensive guides:
- [ML Workflows](docs/guides/ml-workflows.md) - Train/predict patterns and model runners
- [Configuration Management](docs/guides/configuration-management.md) - Config schemas and validation
- [Artifact Storage](docs/guides/artifact-storage.md) - Hierarchical data storage for ML artifacts
- [Task Execution](docs/guides/task-execution.md) - Python functions and shell command templates
- [CLI Scaffolding](docs/guides/cli-scaffolding.md) - Project scaffolding with `chapkit init`
- [Database Migrations](docs/guides/database-migrations.md) - Custom models and Alembic migrations
Full documentation: https://dhis2-chap.github.io/chapkit/
## Testing
```bash
make test # Run tests
make lint # Run linter
make coverage # Test coverage
```
## License
AGPL-3.0-or-later
## Related Projects
- **[servicekit](https://github.com/winterop-com/servicekit)** - Core framework foundation (FastAPI, SQLAlchemy, CRUD, auth, etc.) ([docs](https://winterop-com.github.io/servicekit))
Raw data
{
"_id": null,
"home_page": null,
"name": "chapkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "ml, machine-learning, data-science, artifacts, tasks, config, servicekit",
"author": "Morten Hansen",
"author_email": "Morten Hansen <morten@dhis2.org>",
"download_url": "https://files.pythonhosted.org/packages/62/e5/c61d154c61574083c6221f0580b38a5f2fbf121f595f9b63277d6919c1b0/chapkit-0.4.14.tar.gz",
"platform": null,
"description": "# Chapkit\n\n[](https://github.com/dhis2-chap/chapkit/actions/workflows/ci.yml)\n[](https://codecov.io/gh/dhis2-chap/chapkit)\n[](https://www.python.org/downloads/)\n[](https://www.gnu.org/licenses/agpl-3.0)\n[](https://dhis2-chap.github.io/chapkit/)\n\n> ML service modules built on servicekit - config, artifact, task, and ML workflows\n\nChapkit provides domain-specific modules for building machine learning services on top of servicekit's core framework. Includes artifact storage, task execution, configuration management, and ML train/predict workflows.\n\n## Features\n\n- **Artifact Module**: Hierarchical storage for models, data, and experiment tracking with parent-child relationships\n- **Task Module**: Reusable command templates for shell and Python task execution with parameter injection\n- **Config Module**: Key-value configuration with JSON data and Pydantic validation\n- **ML Module**: Train/predict workflows with artifact-based model storage and timing metadata\n- **Config-Artifact Linking**: Connect configurations to artifact hierarchies for experiment tracking\n\n## Installation\n\nUsing uv (recommended):\n\n```bash\nuv add chapkit\n```\n\nOr using pip:\n\n```bash\npip install chapkit\n```\n\nChapkit automatically installs servicekit as a dependency.\n\n## CLI Usage\n\nQuickly scaffold a new ML service project using `uvx`:\n\n```bash\nuvx chapkit init <project-name>\n```\n\nExample:\n```bash\nuvx chapkit init my-ml-service\n```\n\nOptions:\n- `--path <directory>` - Target directory (default: current directory)\n- `--monitoring` - Include Prometheus and Grafana monitoring stack\n\nThis creates a ready-to-run ML service with configuration, artifacts, and ML endpoints pre-configured.\n\n## Quick Start\n\n```python\nfrom chapkit import ArtifactHierarchy, BaseConfig\nfrom chapkit.api import ServiceBuilder, ServiceInfo\n\nclass MyConfig(BaseConfig):\n model_name: str\n threshold: float\n\napp = (\n ServiceBuilder(info=ServiceInfo(display_name=\"ML Service\"))\n .with_health()\n .with_config(MyConfig)\n .with_artifacts(hierarchy=ArtifactHierarchy(name=\"ml\", level_labels={0: \"model\"}))\n .with_jobs()\n .build()\n)\n```\n\n## Modules\n\n### Config\n\nKey-value configuration storage with Pydantic schema validation:\n\n```python\nfrom chapkit import BaseConfig, ConfigManager\n\nclass AppConfig(BaseConfig):\n api_url: str\n timeout: int = 30\n\n# Automatic validation and CRUD endpoints\napp.with_config(AppConfig)\n```\n\n### Artifacts\n\nHierarchical storage for models, data, and experiment tracking:\n\n```python\nfrom chapkit import ArtifactHierarchy, ArtifactManager, ArtifactIn\n\nhierarchy = ArtifactHierarchy(\n name=\"ml_pipeline\",\n level_labels={0: \"experiment\", 1: \"model\", 2: \"evaluation\"}\n)\n\n# Store pandas DataFrames, models, any Python object\nartifact = await artifact_manager.save(\n ArtifactIn(data=trained_model, parent_id=experiment_id)\n)\n```\n\n### ML\n\nTrain and predict workflows with automatic model storage:\n\n```python\nfrom chapkit.ml import FunctionalModelRunner\nimport pandas as pd\n\nasync def train_model(config: MyConfig, data: pd.DataFrame, geo=None):\n \"\"\"Train your model - returns trained model object.\"\"\"\n from sklearn.linear_model import LinearRegression\n model = LinearRegression()\n model.fit(data[[\"feature1\", \"feature2\"]], data[\"target\"])\n return model\n\nasync def predict(config: MyConfig, model, historic: pd.DataFrame, future: pd.DataFrame, geo=None):\n \"\"\"Make predictions - returns DataFrame with predictions.\"\"\"\n predictions = model.predict(future[[\"feature1\", \"feature2\"]])\n future[\"predictions\"] = predictions\n return future\n\n# Wrap functions in runner\nrunner = FunctionalModelRunner(on_train=train_model, on_predict=predict)\napp.with_ml(runner=runner)\n```\n\n## Architecture\n\n```\nchapkit/\n\u251c\u2500\u2500 config/ # Configuration management with Pydantic validation\n\u251c\u2500\u2500 artifact/ # Hierarchical storage for models and data\n\u251c\u2500\u2500 task/ # Reusable task templates (Python functions, shell commands)\n\u251c\u2500\u2500 ml/ # ML train/predict workflows\n\u251c\u2500\u2500 cli/ # CLI scaffolding tools\n\u251c\u2500\u2500 scheduler.py # Job scheduling integration\n\u2514\u2500\u2500 api/ # ServiceBuilder with ML integration\n \u2514\u2500\u2500 service_builder.py # .with_config(), .with_artifacts(), .with_ml()\n```\n\nChapkit extends servicekit's `BaseServiceBuilder` with ML-specific features and domain modules for configuration, artifacts, tasks, and ML workflows.\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- `quickstart/` - Complete ML service with config, artifacts, and ML endpoints\n- `config_artifact/` - Config with artifact linking\n- `ml_functional/`, `ml_class/`, `ml_shell/` - ML workflow patterns (functional, class-based, shell-based)\n- `ml_pipeline/` - Multi-stage ML pipeline with hierarchical artifacts\n- `artifact/` - Read-only artifact API with hierarchical storage\n- `task_execution/` - Task execution with Python functions and shell commands\n- `full_featured/` - Comprehensive example with monitoring, custom routers, and hooks\n- `library_usage/` - Using chapkit as a library with custom models\n- `custom_migrations/` - Database migrations with custom models\n\n## Documentation\n\nSee `docs/guides/` for comprehensive guides:\n\n- [ML Workflows](docs/guides/ml-workflows.md) - Train/predict patterns and model runners\n- [Configuration Management](docs/guides/configuration-management.md) - Config schemas and validation\n- [Artifact Storage](docs/guides/artifact-storage.md) - Hierarchical data storage for ML artifacts\n- [Task Execution](docs/guides/task-execution.md) - Python functions and shell command templates\n- [CLI Scaffolding](docs/guides/cli-scaffolding.md) - Project scaffolding with `chapkit init`\n- [Database Migrations](docs/guides/database-migrations.md) - Custom models and Alembic migrations\n\nFull documentation: https://dhis2-chap.github.io/chapkit/\n\n## Testing\n\n```bash\nmake test # Run tests\nmake lint # Run linter\nmake coverage # Test coverage\n```\n\n## License\n\nAGPL-3.0-or-later\n\n## Related Projects\n\n- **[servicekit](https://github.com/winterop-com/servicekit)** - Core framework foundation (FastAPI, SQLAlchemy, CRUD, auth, etc.) ([docs](https://winterop-com.github.io/servicekit))\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "ML and data service modules built on servicekit - config, artifacts, tasks, and ML workflows",
"version": "0.4.14",
"project_urls": {
"Documentation": "https://dhis2-chap.github.io/chapkit",
"Homepage": "https://github.com/dhis2-chap/chapkit",
"Issues": "https://github.com/dhis2-chap/chapkit/issues",
"Repository": "https://github.com/dhis2-chap/chapkit"
},
"split_keywords": [
"ml",
" machine-learning",
" data-science",
" artifacts",
" tasks",
" config",
" servicekit"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e6dac4bf2c4b95d5e71b3927de56335a6270a24b43f6020c096c770ef3497765",
"md5": "6d614d3916a524ed23516212b928ecd1",
"sha256": "be9b54f82481de9348679af8e3eb701234e37f29e170054bc5d4b7c86b6eddea"
},
"downloads": -1,
"filename": "chapkit-0.4.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d614d3916a524ed23516212b928ecd1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 60393,
"upload_time": "2025-10-30T13:35:04",
"upload_time_iso_8601": "2025-10-30T13:35:04.605422Z",
"url": "https://files.pythonhosted.org/packages/e6/da/c4bf2c4b95d5e71b3927de56335a6270a24b43f6020c096c770ef3497765/chapkit-0.4.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "62e5c61d154c61574083c6221f0580b38a5f2fbf121f595f9b63277d6919c1b0",
"md5": "636b2c3861889d2df44aa8c6429ab3d0",
"sha256": "9ac79bf30f3f52db1dffc352e3857f61b2a95ef25af3e4e366b8916cff5cef80"
},
"downloads": -1,
"filename": "chapkit-0.4.14.tar.gz",
"has_sig": false,
"md5_digest": "636b2c3861889d2df44aa8c6429ab3d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 41286,
"upload_time": "2025-10-30T13:35:07",
"upload_time_iso_8601": "2025-10-30T13:35:07.514479Z",
"url": "https://files.pythonhosted.org/packages/62/e5/c61d154c61574083c6221f0580b38a5f2fbf121f595f9b63277d6919c1b0/chapkit-0.4.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 13:35:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dhis2-chap",
"github_project": "chapkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chapkit"
}
JSON
