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.0.1

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.0.1
File Size Uploaded Provenance Actions
servicekit-3.0.1.tar.gz 54.2 kB With provenance Details for servicekit-3.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 119.1 kB

Release files / servicekit-3.0.1.tar.gz

Download URL servicekit-3.0.1.tar.gz
Size 54.2 kB
Tags Source
SHA-256 checksum
How to use checksums
c9c8f26bc03adc3a845ac75833834e46315793140e6e2cb3a169d2616000b245
BLAKE2b-256 checksum
How to use checksums
800f9506723128bffd7f87f9db172c9457cce57ca70cc6dce6a62520c879cb36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 19, 2026.

Transparency log

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

Download URL servicekit-3.0.1-py3-none-any.whl
Size 64.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
915c58a5e9b3fcc26669be89ed60fb8ecd8f0d9894bc0fae51c2101cad46d684
BLAKE2b-256 checksum
How to use checksums
7b13e315e0b8695a8879cd07c8bdcca6d858bbc2797ed99910c5eebb03be011a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 19, 2026.

Transparency log

Security for servicekit 3.0.1

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.0.1.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 19, 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