forktex 0.11.0

The shared Python substrate for ForkTex services.

Fourteen modules, one library, one set of opinions. Import only what you need — each module's third-party dependency is an optional extra, so a service that wants structured logging never pays for Qdrant.

forktex 0.9.0 is a different package from forktex 0.8.x. Up to 0.8.1 this name shipped an agentic CLI. That tool now lives in backlog/ pending republication under its own name. If you want the CLI, pin forktex==0.8.1.

pip install forktex

Modules

Primitives — always available, no extra required:

Role facades — one per piece of infrastructure:

Bootstrap — process-level wiring:

Install extras as needed — pip install "forktex[storage,vector]", or pip install "forktex[all]" for everything.

Quick start

from contextlib import asynccontextmanager

from fastapi import Depends, FastAPI
from sqlalchemy.ext.asyncio import AsyncSession

from forktex.database import close_engine, init_engine, session_scope
from forktex.log import setup_logging

setup_logging(service="my-api")


@asynccontextmanager
async def lifespan(app: FastAPI):
    init_engine(settings.db_url, pool_pre_ping=True, pool_recycle=1800)
    yield
    await close_engine()


app = FastAPI(lifespan=lifespan)


@app.get("/projects")
async def list_projects(session: AsyncSession = Depends(session_scope)):
    ...

Depends(session_scope) is the correct form. get_session is the same generator wrapped in asynccontextmanager for async with use in service code — passing it to Depends injects the context-manager object, not a session. See docs/database.md.

A module whose extra is missing raises an ImportError that names it:

ImportError: Install 'forktex[vector]' (qdrant-client) to use forktex.vector

Documentation

One page per module under docs/, each covering install, wiring, the public surface, the error contract, and measured gotchas. docs/development.md is the contributor guide.

Development

make install     # poetry install --with dev --all-extras
make test        # pytest with the coverage floor
make ci          # format-check · lint · license-check · typecheck · audit · test · build · smoke

Integration tests run against real Postgres, Redis, MinIO, Qdrant and MongoDB via testcontainers — Docker must be available.

License

Dual-licensed: AGPL-3.0-or-later, or a commercial license from FORKTEX S.R.L. (info@forktex.com). See LICENSE and NOTICE.