chapkit 0.6.4__py3-none-any.whl

chapkit/__init__.py

@@ -0,0 +1,125 @@
+"""Chapkit - ML/data service modules built on servicekit."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Read version from package metadata - must be before internal imports
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("chapkit")
+except Exception:
+    __version__ = "unknown"
+
+# 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,
+)
+
+# Data feature
+from .data import DataFrame, GroupBy
+
+# 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,
+)
+
+
+def get_alembic_dir() -> Path:
+    """Get the path to chapkit's bundled alembic migrations directory."""
+    return Path(__file__).parent / "alembic"
+
+
+__all__ = [
+    # Version
+    "__version__",
+    # Utils
+    "get_alembic_dir",
+    # CLI
+    "cli_app",
+    # Scheduler
+    "ChapkitJobRecord",
+    "ChapkitJobScheduler",
+    # Artifact
+    "Artifact",
+    "ArtifactHierarchy",
+    "ArtifactIn",
+    "ArtifactManager",
+    "ArtifactOut",
+    "ArtifactRepository",
+    "ArtifactRouter",
+    "ArtifactTreeNode",
+    # Config
+    "BaseConfig",
+    "Config",
+    "ConfigIn",
+    "ConfigManager",
+    "ConfigOut",
+    "ConfigRepository",
+    # Data
+    "DataFrame",
+    "GroupBy",
+    # ML
+    "FunctionalModelRunner",
+    "MLManager",
+    "MLRouter",
+    "ModelRunnerProtocol",
+    "PredictionArtifactData",
+    "PredictRequest",
+    "PredictResponse",
+    "TrainedModelArtifactData",
+    "TrainRequest",
+    "TrainResponse",
+    # Task
+    "Task",
+    "TaskIn",
+    "TaskManager",
+    "TaskOut",
+    "TaskRegistry",
+    "TaskRepository",
+    "TaskRouter",
+    "validate_and_disable_orphaned_tasks",
+]

chapkit/alembic/__init__.py

@@ -0,0 +1 @@
+"""Chapkit database migrations."""

chapkit/alembic/env.py

@@ -0,0 +1,76 @@
+"""Alembic environment configuration for async SQLAlchemy migrations."""
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+
+# Import the Base metadata from servicekit
+from servicekit import Base
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# This is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging (if present)
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set target metadata for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode (generates SQL scripts)."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Run migrations with a connection."""
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations in async mode using async engine."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode (connects to database)."""
+    # Since we're being called from Database.init() via run_in_executor,
+    # we're in a separate thread and can safely create a new event loop
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(run_async_migrations())
+    finally:
+        loop.close()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

chapkit/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Apply database schema changes."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Revert database schema changes."""
+    ${downgrades if downgrades else "pass"}

chapkit/alembic/versions/20251010_0927_4d869b5fb06e_initial_schema.py

@@ -0,0 +1,38 @@
+"""Initial database schema migration."""
+
+from alembic import op
+
+from chapkit.alembic_helpers import (
+    create_artifacts_table,
+    create_config_artifacts_table,
+    create_configs_table,
+    create_tasks_table,
+    drop_artifacts_table,
+    drop_config_artifacts_table,
+    drop_configs_table,
+    drop_tasks_table,
+)
+
+# revision identifiers, used by Alembic.
+revision = "4d869b5fb06e"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Apply database schema changes."""
+    # Chapkit domain tables
+    create_artifacts_table(op)
+    create_configs_table(op)
+    create_config_artifacts_table(op)
+    create_tasks_table(op)
+
+
+def downgrade() -> None:
+    """Revert database schema changes."""
+    # Drop in reverse order
+    drop_tasks_table(op)
+    drop_config_artifacts_table(op)
+    drop_configs_table(op)
+    drop_artifacts_table(op)

chapkit/alembic/versions/__init__.py

@@ -0,0 +1 @@
+"""Alembic migration versions."""

chapkit/alembic_helpers.py

@@ -0,0 +1,138 @@
+"""Reusable Alembic migration helpers for chapkit tables.
+
+This module provides helper functions for creating and dropping chapkit's database tables
+in Alembic migrations. Using helpers instead of raw Alembic operations provides:
+
+- Reusability across migrations
+- Consistent table definitions
+- Clear documentation
+- Easier maintenance
+
+Users can create their own helper modules following this pattern for custom tables.
+
+Example:
+    # In your migration file
+    from chapkit.alembic_helpers import create_configs_table, drop_configs_table
+
+    def upgrade() -> None:
+        create_configs_table(op)
+
+    def downgrade() -> None:
+        drop_configs_table(op)
+
+Creating Your Own Helpers:
+    Follow the same pattern for your custom tables:
+
+    # myapp/alembic_helpers.py
+    def create_users_table(op: Any) -> None:
+        '''Create users table.'''
+        op.create_table(
+            'users',
+            sa.Column('email', sa.String(), nullable=False),
+            sa.Column('name', sa.String(), nullable=False),
+            sa.Column('id', servicekit.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),
+            sa.Column('tags', sa.JSON(), nullable=False, server_default='[]'),
+            sa.PrimaryKeyConstraint('id'),
+        )
+        op.create_index(op.f('ix_users_email'), 'users', ['email'], unique=False)
+
+    def drop_users_table(op: Any) -> None:
+        '''Drop users table.'''
+        op.drop_index(op.f('ix_users_email'), table_name='users')
+        op.drop_table('users')
+
+See examples/custom_migrations/ for a complete working example.
+"""
+
+from typing import Any
+
+import servicekit.types
+import sqlalchemy as sa
+
+
+def create_artifacts_table(op: Any) -> None:
+    """Create artifacts table for hierarchical artifact storage."""
+    op.create_table(
+        "artifacts",
+        sa.Column("parent_id", servicekit.types.ULIDType(length=26), nullable=True),
+        sa.Column("data", sa.PickleType(), nullable=False),
+        sa.Column("level", sa.Integer(), nullable=False),
+        sa.Column("id", servicekit.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),
+        sa.Column("tags", sa.JSON(), nullable=False, server_default="[]"),
+        sa.ForeignKeyConstraint(["parent_id"], ["artifacts.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_artifacts_level"), "artifacts", ["level"], unique=False)
+    op.create_index(op.f("ix_artifacts_parent_id"), "artifacts", ["parent_id"], unique=False)
+
+
+def drop_artifacts_table(op: Any) -> None:
+    """Drop artifacts table."""
+    op.drop_index(op.f("ix_artifacts_parent_id"), table_name="artifacts")
+    op.drop_index(op.f("ix_artifacts_level"), table_name="artifacts")
+    op.drop_table("artifacts")
+
+
+def create_configs_table(op: Any) -> None:
+    """Create configs table for configuration storage."""
+    op.create_table(
+        "configs",
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("data", sa.JSON(), nullable=False),
+        sa.Column("id", servicekit.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),
+        sa.Column("tags", sa.JSON(), nullable=False, server_default="[]"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_configs_name"), "configs", ["name"], unique=False)
+
+
+def drop_configs_table(op: Any) -> None:
+    """Drop configs table."""
+    op.drop_index(op.f("ix_configs_name"), table_name="configs")
+    op.drop_table("configs")
+
+
+def create_config_artifacts_table(op: Any) -> None:
+    """Create config_artifacts junction table linking configs to artifacts."""
+    op.create_table(
+        "config_artifacts",
+        sa.Column("config_id", servicekit.types.ULIDType(length=26), nullable=False),
+        sa.Column("artifact_id", servicekit.types.ULIDType(length=26), nullable=False),
+        sa.ForeignKeyConstraint(["artifact_id"], ["artifacts.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["config_id"], ["configs.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("config_id", "artifact_id"),
+        sa.UniqueConstraint("artifact_id"),
+        sa.UniqueConstraint("artifact_id", name="uq_artifact_id"),
+    )
+
+
+def drop_config_artifacts_table(op: Any) -> None:
+    """Drop config_artifacts junction table."""
+    op.drop_table("config_artifacts")
+
+
+def create_tasks_table(op: Any) -> None:
+    """Create tasks table for task execution infrastructure."""
+    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", servicekit.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),
+        sa.Column("tags", sa.JSON(), nullable=False, server_default="[]"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def drop_tasks_table(op: Any) -> None:
+    """Drop tasks table."""
+    op.drop_table("tasks")

chapkit/api/__init__.py

@@ -0,0 +1,64 @@
+"""FastAPI routers and related presentation logic."""
+
+from servicekit.api import CrudPermissions, CrudRouter, Router
+from servicekit.api.middleware import (
+    add_error_handlers,
+    add_logging_middleware,
+    database_error_handler,
+    validation_error_handler,
+)
+from servicekit.api.routers import HealthRouter, HealthState, HealthStatus, JobRouter, SystemInfo, SystemRouter
+from servicekit.api.service_builder import ServiceInfo
+from servicekit.api.utilities import build_location_url, run_app
+from servicekit.logging import (
+    add_request_context,
+    clear_request_context,
+    configure_logging,
+    get_logger,
+    reset_request_context,
+)
+
+from chapkit.artifact import ArtifactRouter
+from chapkit.config import ConfigRouter
+
+from .dependencies import get_artifact_manager, get_config_manager
+from .service_builder import AssessedStatus, MLServiceBuilder, MLServiceInfo, ServiceBuilder
+
+__all__ = [
+    # Base classes
+    "Router",
+    "CrudRouter",
+    "CrudPermissions",
+    # Routers
+    "HealthRouter",
+    "HealthStatus",
+    "HealthState",
+    "JobRouter",
+    "SystemRouter",
+    "SystemInfo",
+    "ConfigRouter",
+    "ArtifactRouter",
+    # Dependencies
+    "get_config_manager",
+    "get_artifact_manager",
+    # Middleware
+    "add_error_handlers",
+    "add_logging_middleware",
+    "database_error_handler",
+    "validation_error_handler",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "add_request_context",
+    "clear_request_context",
+    "reset_request_context",
+    # Builders
+    "ServiceBuilder",
+    "MLServiceBuilder",
+    "ServiceInfo",
+    "MLServiceInfo",
+    "AssessedStatus",
+    # Utilities
+    "build_location_url",
+    "run_app",
+]

chapkit/api/dependencies.py

@@ -0,0 +1,32 @@
+"""Feature-specific FastAPI dependency injection for managers."""
+
+from typing import Annotated
+
+from fastapi import Depends
+from servicekit.api.dependencies import get_session
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from chapkit.artifact import ArtifactManager, ArtifactRepository
+from chapkit.config import BaseConfig, ConfigManager, ConfigRepository
+from chapkit.ml import MLManager
+
+
+async def get_config_manager(session: Annotated[AsyncSession, Depends(get_session)]) -> ConfigManager[BaseConfig]:
+    """Get a config manager instance for dependency injection."""
+    repo = ConfigRepository(session)
+    return ConfigManager[BaseConfig](repo, BaseConfig)
+
+
+async def get_artifact_manager(session: Annotated[AsyncSession, Depends(get_session)]) -> ArtifactManager:
+    """Get an artifact manager instance for dependency injection."""
+    artifact_repo = ArtifactRepository(session)
+    return ArtifactManager(artifact_repo)
+
+
+async def get_ml_manager() -> MLManager:
+    """Get an ML manager instance for dependency injection.
+
+    Note: This is a placeholder. The actual dependency is built by ServiceBuilder
+    with the runner in closure, then overridden via app.dependency_overrides.
+    """
+    raise RuntimeError("ML manager dependency not configured. Use ServiceBuilder.with_ml() to enable ML operations.")