Skip to main content

Servicekit

CI PyPI version codecov Python 3.13+ License: AGPL v3 Documentation

Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services

Servicekit is a framework-agnostic core library providing foundational infrastructure for building async Python services with FastAPI and SQLAlchemy.

Features

  • Database Layer: Async SQLAlchemy with SQLite support, connection pooling, and automatic migrations
  • Repository Pattern: Generic repository base classes for data access
  • Manager Pattern: Business logic layer with lifecycle hooks
  • CRUD API: Auto-generated REST endpoints with full CRUD operations
  • Authentication: API key middleware with file and environment variable support
  • Job Scheduling: Async job scheduler with concurrency control
  • App Hosting: Mount static web applications alongside your API
  • Monitoring: Prometheus metrics and OpenTelemetry integration
  • Health Checks: Flexible health check system with SSE streaming support
  • Error Handling: RFC 9457 Problem Details for HTTP APIs
  • Logging: Structured logging with request context

Installation

pip install servicekit

Quick Start

from servicekit.api import BaseServiceBuilder, ServiceInfo

app = (
    BaseServiceBuilder(info=ServiceInfo(id="my-service", display_name="My Service"))
    .with_health()
    .with_database("sqlite+aiosqlite:///./data.db")
    .build()
)

Architecture

servicekit/
├── database.py       # Database, SqliteDatabase, SqliteDatabaseBuilder
├── models.py         # Base, Entity ORM classes
├── repository.py     # Repository, BaseRepository
├── manager.py        # Manager, BaseManager
├── schemas.py        # EntityIn, EntityOut, PaginatedResponse
├── scheduler.py      # Scheduler, InMemoryScheduler
├── exceptions.py     # Error classes
├── logging.py        # Structured logging
├── types.py          # ULIDType, JsonSafe
└── api/              # FastAPI framework layer
    ├── router.py     # Router base class
    ├── crud.py       # CrudRouter, CrudPermissions
    ├── auth.py       # API key authentication
    ├── app.py        # Static app hosting
    ├── middleware.py # Error handlers, logging
    └── routers/      # Health, Jobs, System, Metrics

Key Components

BaseServiceBuilder

from servicekit.api import BaseServiceBuilder, ServiceInfo

app = (
    BaseServiceBuilder(info=ServiceInfo(id="my-service", display_name="My Service"))
    .with_health()                    # Health check endpoint
    .with_database(url)               # Database configuration
    .with_jobs(max_concurrency=10)   # Job scheduler
    .with_auth()                      # API key authentication
    .with_monitoring()                # Prometheus metrics (on by default)
    .with_app("./webapp")             # Static web app
    .include_router(custom_router)   # Custom routes
    .build()
)

Database Migrations

File-based databases run Alembic migrations on init() by default; in-memory databases create tables directly from the ORM metadata. The migration bundled with servicekit is a framework baseline: it creates only the alembic_version table and no application tables. Applications that define their own entities must either point migrations at their own migration directory or disable migrations and create tables directly.

from pathlib import Path

from servicekit import SqliteDatabaseBuilder, get_alembic_dir

# Application-owned migrations
database = (
    SqliteDatabaseBuilder.from_file("app.db")
    .with_migrations(enabled=True, alembic_dir=Path("alembic"))
    .build()
)

# No migrations - create tables directly from ORM metadata
database = SqliteDatabaseBuilder.from_file("app.db").with_migrations(enabled=False).build()

# Path to the migration environment shipped inside the servicekit package
bundled_migrations = get_alembic_dir()

Repository Pattern

from servicekit import BaseRepository, Entity
from sqlalchemy.orm import Mapped, mapped_column

class User(Entity):
    __tablename__ = "users"
    name: Mapped[str] = mapped_column()
    email: Mapped[str] = mapped_column()

class UserRepository(BaseRepository[User, ULID]):
    def __init__(self, session: AsyncSession):
        super().__init__(session, User)

CRUD Router

from servicekit.api import CrudRouter, CrudPermissions

router = CrudRouter.create(
    prefix="/api/v1/users",
    tags=["Users"],
    entity_in_type=UserIn,
    entity_out_type=UserOut,
    manager_factory=get_user_manager,
    permissions=CrudPermissions(create=True, read=True, update=True, delete=False)
)

POST creates only and returns 409 Conflict for an ID that already exists or for any other database constraint violation. PUT applies the fields sent: an omitted field keeps its value, an explicit null clears a nullable field. Collection listings are ordered by ID, and pagination is opt-in through page (>= 1) and size (1-100), which return 422 when out of range.

Examples

See the examples/ directory for complete working examples:

  • core_api/main.py - Basic CRUD service
  • job_scheduler/main.py - Background job execution
  • app_hosting/main.py - Hosting static web apps
  • auth/main.py - API key authentication
  • monitoring/main.py - Prometheus metrics

Documentation

See docs/ for comprehensive guides and API reference.

Testing

make test      # Run tests
make format    # Format code and apply lint fixes
make lint      # Check formatting, linting and types
make coverage  # Test coverage

License

AGPL-3.0-or-later

  • chapkit - Domain modules (artifacts, configs, tasks, ML workflows) built on servicekit (docs)

Metadata

Release files for servicekit 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for servicekit 3.1.0
File Size Uploaded Provenance Actions
servicekit-3.1.0.tar.gz 54.3 kB With provenance Details for servicekit-3.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for servicekit 3.1.0
File Interpreter ABI Platform Actions
servicekit-3.1.0-py3-none-any.whl Python 3 none any Details for servicekit-3.1.0-py3-none-any.whl

Total release size: 119.2 kB

Release files / servicekit-3.1.0.tar.gz

Download URL servicekit-3.1.0.tar.gz
Size 54.3 kB
Tags Source
SHA-256 checksum
How to use checksums
5f38ea18608873dc22dab7e4d040f6b51902ac8eb60f95cf01bf27f4258f8eec
BLAKE2b-256 checksum
How to use checksums
30fe44a3af471e60f8f2c167e0c0b03cf93ed1e75d3b59ef43cf44d0add7ee87
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / servicekit-3.1.0-py3-none-any.whl

Download URL servicekit-3.1.0-py3-none-any.whl
Size 65.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
38d5a8f2572a3a2031dc15130b0ca664d9795f45ac4414154be0aa1e71d7522e
BLAKE2b-256 checksum
How to use checksums
c56bfe7d5f9c895fe7bbbf9ffa8d955da418bbdada067006037cc7ff2508e808
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for servicekit 3.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for servicekit-3.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page