forktex 0.13.0

The shared Python substrate for ForkTex services.

One install, no extras: import forktex resolves every module.

pip install forktex

This is not the 0.8.x forktex, which was an agentic CLI — for that, pin forktex==0.8.1. Pre-1.0, minor versions may break; see CHANGELOG.md.

Modules

Primitives

Role facades — one per piece of infrastructure:

Bootstrap — process-level wiring:

graph, queue, store, vault and vector are set aside in backlog/facades/ until a consumer needs them.

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, yield_transactional_session
from forktex.log import setup_logging

setup_logging(service="my-api")


@asynccontextmanager
async def lifespan(app: FastAPI):
    await 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(yield_transactional_session)):
    ...

Transactions

The outermost caller owns the transaction: whoever opens it commits it once, and rolls it back on any exception.

@with_transactional_session
async def place_order(session: AsyncSession, *, reference: str) -> Order:
    return await create(session, Order, reference=reference)


await place_order(reference="A-1")                       # opens a session, commits it

async with transactional_session() as session:
    order = await place_order(session, reference="A-2")   # joins this transaction
    await add_line(session, order=order, sku="X")         # the same one
    raise PaymentFailed                                   # both roll back

Inside the first two, commit(), rollback() and begin() raise TransactionBoundaryError. To abort, raise. Full contract in docs/database.md.

init_engine / cache.init / storage.init configure one process-wide default; Database(url), Cache(url) and StorageClient(config) build handles directly, so a process can hold several.

Documentation

One page per module under docs/: wiring, the public surface, the error contract, the gotchas. docs/development.md is the contributor guide.

Development

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

Integration tests use testcontainers, so 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.