forktex-core 0.1.1

Shared database (PostgreSQL) and cache (Redis) primitives for the FORKTEX ecosystem

forktex-core

Shared PostgreSQL and Redis primitives for the ForkTex ecosystem.

forktex-core is the foundation library every ForkTex Python service depends on. It owns the async SQLAlchemy engine, session helpers, ORM mixins, and Redis caching primitives, so individual services don't reinvent connection management.

What This Repo Ships

This repo ships exactly one package: forktex-core on PyPI.

It is consumed as a runtime dependency by:

• forktex-cloud-api (cloud platform server) — from forktex_core.psql.connection import init_engine, get_session
• forktex-intelligence-api (intelligence platform server) — same
• any future ForkTex Python service that needs PostgreSQL or Redis

Install

pip install forktex-core

PostgreSQL (asyncpg + SQLAlchemy 2) and Redis (hiredis) are both included by default — there are no optional extras you need to remember.

Quick Start

PostgreSQL

from forktex_core.psql import (
    init_engine, close_engine, get_session,
    BaseDBModel, TimestampMixin, AuditMixin,
)

# Initialize once in your app's lifespan
init_engine("postgresql+asyncpg://user:pass@localhost/db")

# Use a session anywhere
async with get_session() as session:
    user = await session.get(User, user_id)

Tunable engine kwargs are passed straight through to create_async_engine:

init_engine(
    "postgresql+asyncpg://user:pass@host/db",
    pool_size=20,
    max_overflow=10,
    pool_pre_ping=True,
)

Redis

from forktex_core.redis import init, close, cached

await init("redis://localhost:6379/0")

@cached(ttl=300)
async def get_profile(user_id: str):
    ...

Operate

The root Makefile is generated by forktex fsd makefile sync. Do not hand-edit it.

make help              # list every available target
make deps              # pip install -e .
make format            # ruff format
make lint              # ruff check
make test              # pytest tests/
make build             # python3 -m build → dist/
make publish           # twine upload dist/*
make clean             # remove caches and dist/
make ci                # format-check + lint + test

make start / make stop / make logs are intentional no-ops — forktex-core is a library, there's nothing to run.

FSD Self-Description

This repo follows the ForkTex Standard Delivery (FSD) shape:

• root manifest: forktex.json
• manifest schema version: manifestVersion = 1.0.0
• FSD contract version: fsd.version = 1.0.0
• profile: workspace/python-monorepo
• target maturity: L3
• single publishable package: forktex-core at path .

Re-validate locally with:

forktex fsd --project-dir . check
forktex arch discover --project-dir . --output-dir /tmp/arch-corepy

Repository Layout

core-py/
├── forktex.json
├── Makefile
├── pyproject.toml
├── README.md
└── src/forktex_core/
    ├── psql/        # async SQLAlchemy engine, sessions, ORM mixins
    └── redis/       # connection, namespaces, ops, decorators

License

MIT — see LICENSE.