chapkit 0.4.5__tar.gz

chapkit-0.4.5/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: chapkit
+Version: 0.4.5
+Summary: ML and data service modules built on servicekit - config, artifacts, tasks, and ML workflows
+Keywords: ml,machine-learning,data-science,artifacts,tasks,config,servicekit
+Author: Morten Hansen
+Author-email: Morten Hansen <morten@dhis2.org>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: geojson-pydantic>=2.1.0
+Requires-Dist: typer>=0.20.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: servicekit>=0.3.5
+Requires-Python: >=3.13
+Project-URL: Documentation, https://dhis2-chap.github.io/chapkit
+Project-URL: Homepage, https://github.com/dhis2-chap/chapkit
+Project-URL: Issues, https://github.com/dhis2-chap/chapkit/issues
+Project-URL: Repository, https://github.com/dhis2-chap/chapkit
+Description-Content-Type: text/markdown
+
+# Chapkit
+
+[![CI](https://github.com/dhis2-chap/chapkit/actions/workflows/ci.yml/badge.svg)](https://github.com/dhis2-chap/chapkit/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dhis2-chap/chapkit/branch/main/graph/badge.svg)](https://codecov.io/gh/dhis2-chap/chapkit)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](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
+
+```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@git+https://github.com/dhis2-chap/chapkit init <project-name>
+```
+
+Example:
+```bash
+uvx chapkit@git+https://github.com/dhis2-chap/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 module
+├── ml/               # ML train/predict workflows
+└── api/              # ServiceBuilder with ML integration
+    └── service_builder.py  # .with_config(), .with_ml()
+```
+
+Chapkit extends servicekit's `BaseServiceBuilder` with ML-specific features and uses servicekit's artifact and task modules.
+
+## Examples
+
+See the `examples/` directory:
+
+- `quickstart.py` - Complete ML service
+- `config_artifact_api.py` - Config with artifact linking
+- `ml_basic.py`, `ml_class.py` - ML workflow patterns
+
+## Documentation
+
+See `docs/` for comprehensive guides:
+
+- ML workflow guide
+
+## 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))

chapkit-0.4.5/README.md

@@ -0,0 +1,169 @@
+# Chapkit
+
+[![CI](https://github.com/dhis2-chap/chapkit/actions/workflows/ci.yml/badge.svg)](https://github.com/dhis2-chap/chapkit/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dhis2-chap/chapkit/branch/main/graph/badge.svg)](https://codecov.io/gh/dhis2-chap/chapkit)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](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
+
+```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@git+https://github.com/dhis2-chap/chapkit init <project-name>
+```
+
+Example:
+```bash
+uvx chapkit@git+https://github.com/dhis2-chap/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 module
+├── ml/               # ML train/predict workflows
+└── api/              # ServiceBuilder with ML integration
+    └── service_builder.py  # .with_config(), .with_ml()
+```
+
+Chapkit extends servicekit's `BaseServiceBuilder` with ML-specific features and uses servicekit's artifact and task modules.
+
+## Examples
+
+See the `examples/` directory:
+
+- `quickstart.py` - Complete ML service
+- `config_artifact_api.py` - Config with artifact linking
+- `ml_basic.py`, `ml_class.py` - ML workflow patterns
+
+## Documentation
+
+See `docs/` for comprehensive guides:
+
+- ML workflow guide
+
+## 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))

chapkit-0.4.5/pyproject.toml

@@ -0,0 +1,161 @@
+[project]
+name = "chapkit"
+version = "0.4.5"
+description = "ML and data service modules built on servicekit - config, artifacts, tasks, and ML workflows"
+readme = "README.md"
+authors = [{ name = "Morten Hansen", email = "morten@dhis2.org" }]
+license = { text = "AGPL-3.0-or-later" }
+requires-python = ">=3.13"
+keywords = [
+  "ml",
+  "machine-learning",
+  "data-science",
+  "artifacts",
+  "tasks",
+  "config",
+  "servicekit",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: FastAPI",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "geojson-pydantic>=2.1.0",
+  "typer>=0.20.0",
+  "jinja2>=3.1.6",
+  "servicekit>=0.3.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/dhis2-chap/chapkit"
+Repository = "https://github.com/dhis2-chap/chapkit"
+Issues = "https://github.com/dhis2-chap/chapkit/issues"
+Documentation = "https://dhis2-chap.github.io/chapkit"
+
+[project.scripts]
+chapkit = "chapkit.cli.cli:main"
+
+[dependency-groups]
+dev = [
+  "coverage[toml]>=7.6.0",
+  "mypy>=1.18.2",
+  "pandas-stubs>=2.2.3.250101",
+  "pytest>=8.4.2",
+  "pytest-cov>=5.0.0",
+  "pytest-asyncio>=1.2.0",
+  "ruff>=0.14.0",
+  "pyright>=1.1.407",
+  "scikit-learn>=1.7.2",
+  "mkdocs>=1.6.0",
+  "mkdocs-material>=9.5.0",
+  "mkdocstrings[python]>=0.26.0",
+  "types-pyyaml>=6.0.12.20250915",
+  "pandas>=2.3.3",
+  "polars>=1.34.0",
+  "xarray>=2025.10.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+select = ["E", "W", "F", "I", "D"]
+ignore = ["D203", "D213"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+"alembic/**/*.py" = ["D"]
+"**/__init__.py" = ["D104"]
+"src/**/*.py" = ["D102", "D105", "D107"]
+"examples/**/*.py" = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+norecursedirs = ["examples", ".git", ".venv", "__pycache__"]
+filterwarnings = [
+  "ignore:Pydantic serializer warnings:UserWarning",
+  "ignore:Remove.*format_exc_info.*:UserWarning",
+]
+
+[tool.coverage.run]
+branch = true
+dynamic_context = "test_function"
+relative_files = true
+source = ["chapkit"]
+
+[tool.coverage.report]
+exclude_also = ["if TYPE_CHECKING:"]
+precision = 2
+show_missing = true
+skip_covered = true
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_unused_ignores = true
+strict_equality = true
+mypy_path = ["src", "typings"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "servicekit.*"
+ignore_missing_imports = true
+disallow_any_unimported = false
+
+[[tool.mypy.overrides]]
+module = [
+  "chapkit.artifact.*",
+  "chapkit.config.*",
+  "chapkit.task.*",
+  "examples.*",
+]
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = "examples.custom_migrations.*"
+ignore_missing_imports = true
+ignore_errors = true
+
+[tool.pyright]
+include = ["src", "tests", "examples", "alembic"]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+useLibraryCodeForTypes = true
+reportPrivateUsage = false
+reportUnusedFunction = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownParameterType = false
+reportUnknownVariableType = false
+reportMissingTypeArgument = false
+reportMissingTypeStubs = false

chapkit-0.4.5/src/chapkit/__init__.py

@@ -0,0 +1,97 @@
+"""Chapkit - ML/data service modules built on servicekit."""
+
+# CLI feature
+# Scheduler feature
+# Artifact feature
+from .artifact import (
+    Artifact,
+    ArtifactHierarchy,
+    ArtifactIn,
+    ArtifactManager,
+    ArtifactOut,
+    ArtifactRepository,
+    ArtifactRouter,
+    ArtifactTreeNode,
+)
+from .cli import app as cli_app
+
+# Config feature
+from .config import (
+    BaseConfig,
+    Config,
+    ConfigIn,
+    ConfigManager,
+    ConfigOut,
+    ConfigRepository,
+)
+
+# ML feature
+from .ml import (
+    FunctionalModelRunner,
+    MLManager,
+    MLRouter,
+    ModelRunnerProtocol,
+    PredictionArtifactData,
+    PredictRequest,
+    PredictResponse,
+    TrainedModelArtifactData,
+    TrainRequest,
+    TrainResponse,
+)
+from .scheduler import ChapkitJobRecord, ChapkitJobScheduler
+
+# Task feature
+from .task import (
+    Task,
+    TaskIn,
+    TaskManager,
+    TaskOut,
+    TaskRegistry,
+    TaskRepository,
+    TaskRouter,
+    validate_and_disable_orphaned_tasks,
+)
+
+__all__ = [
+    # CLI
+    "cli_app",
+    # Scheduler
+    "ChapkitJobRecord",
+    "ChapkitJobScheduler",
+    # Artifact
+    "Artifact",
+    "ArtifactHierarchy",
+    "ArtifactIn",
+    "ArtifactManager",
+    "ArtifactOut",
+    "ArtifactRepository",
+    "ArtifactRouter",
+    "ArtifactTreeNode",
+    # Config
+    "BaseConfig",
+    "Config",
+    "ConfigIn",
+    "ConfigManager",
+    "ConfigOut",
+    "ConfigRepository",
+    # ML
+    "FunctionalModelRunner",
+    "MLManager",
+    "MLRouter",
+    "ModelRunnerProtocol",
+    "PredictionArtifactData",
+    "PredictRequest",
+    "PredictResponse",
+    "TrainedModelArtifactData",
+    "TrainRequest",
+    "TrainResponse",
+    # Task
+    "Task",
+    "TaskIn",
+    "TaskManager",
+    "TaskOut",
+    "TaskRegistry",
+    "TaskRepository",
+    "TaskRouter",
+    "validate_and_disable_orphaned_tasks",
+]