VeloIQ Python API: All Public Framework Exports

The veloiq_framework package exposes every symbol you need to build a full-stack VeloIQ application: the app factory, SQLModel base classes, a relationship wrapper with cardinality metadata, automatic CRUD router generation, role-based and row-level access control decorators, and FastAPI dependencies for auth and database sessions.

Installation

pip install veloiq-framework

App factory

`create_veloiq_app`

from veloiq_framework import create_veloiq_app, VeloIQConfig

app = create_veloiq_app(config: VeloIQConfig | None = None, **kwargs) -> FastAPI

Creates and returns a fully configured FastAPI application. When config is omitted, VeloIQConfig is constructed from environment variables and any **kwargs you pass. The returned app is a standard FastAPI instance — you can add routes, middleware, or dependencies on top.

config

VeloIQConfig | None

A VeloIQConfig instance. If None, one is built from environment variables. See Configuration.

**kwargs

Any

Forwarded to VeloIQConfig when config is not provided. Accepts the same fields as VeloIQConfig.

from veloiq_framework import create_veloiq_app

app = create_veloiq_app()   # DATABASE_URL read from environment

from veloiq_framework import create_veloiq_app, VeloIQConfig

app = create_veloiq_app(VeloIQConfig(
    title="Acme Admin",
    database_url="postgresql://user:pass@localhost/acme",
    modules_dir="app/modules",
))

create_veloiq_app raises ValueError if no DATABASE_URL can be determined from the config or the environment.

Base models

All base classes extend SQLModel. Declare your tables by inheriting from one of these classes with table=True.

`FrameworkModel`

Minimal base model providing a standard auto-increment integer primary key named id. Use this when you do not need timestamp columns.

from veloiq_framework import FrameworkModel

class Category(FrameworkModel, table=True):
    __tablename__ = "category"
    name: str
    slug: str

Field	Type	Description
`id`	`Optional[int]`	Auto-increment primary key.

`TimestampedModel`

Extends FrameworkModel with automatic created_at and updated_at columns. The schema generator appends these two fields after all fields you declare, so they appear last in every list, form, and detail view.

from veloiq_framework import TimestampedModel

class Order(TimestampedModel, table=True):
    __tablename__ = "order"
    reference: str
    total: float
    status: str = "pending"

Field	Type	Description
`id`	`Optional[int]`	Inherited from `FrameworkModel`. Auto-increment PK.
`created_at`	`Optional[datetime]`	Set on insert. Never overwritten by CRUD updates.
`updated_at`	`Optional[datetime]`	Updated automatically on every write.

`StandardModel`

CubicWeb-compatible base model for applications that require eid as the primary key and cw_ column naming conventions. The eid Python attribute maps to the cw_eid physical column. Use this only when migrating from CubicWeb or maintaining an existing CubicWeb schema; new applications should use FrameworkModel or TimestampedModel.

from veloiq_framework import StandardModel
from sqlmodel import Field
from sqlalchemy import Column, String

class LegacyItem(StandardModel, table=True):
    __tablename__ = "legacy_item"
    cw_name: str = Field(sa_column=Column("cw_name", String))

Field	Type	Description
`eid`	`Optional[int]`	Maps to `cw_eid` column. Auto-increment PK.
`creation_date`	`Optional[datetime]`	Set on insert.
`modification_date`	`Optional[datetime]`	Updated automatically on every write.

Relationships

`jm_relationship`

jm_relationship(
    *,
    min_items: int = 0,
    max_items: int | None = None,
    required: bool = False,
    **kwargs: Any,
) -> Any

SQLModel Relationship wrapper that attaches cardinality metadata. The DynamicResource UI component reads this metadata to render required/optional indicators and pagination hints. All **kwargs are passed through to SQLModel’s Relationship.

min_items

int

default:"0"

Minimum number of related items (used for UI validation hints).

max_items

int | None

default:"None"

Maximum number of related items. None means unbounded.

required

bool

default:"False"

Whether the relation is required.

**kwargs

Any

Passed directly to SQLModel’s Relationship (e.g. back_populates, link_model).

from typing import List, Optional
from sqlmodel import Field
from veloiq_framework import TimestampedModel, jm_relationship

class Customer(TimestampedModel, table=True):
    __tablename__ = "customer"
    name: str
    orders: List["Order"] = jm_relationship(back_populates="customer")

class Order(TimestampedModel, table=True):
    __tablename__ = "order"
    reference: str
    customer_id: Optional[int] = Field(default=None, foreign_key="customer.id")
    customer: Optional["Customer"] = jm_relationship(back_populates="orders")

`RelationCardinality`

Dataclass stored in the SQLAlchemy relationship info dict by jm_relationship. You do not normally construct this directly.

Field	Type	Default	Description
`min_items`	`int`	`0`	Minimum cardinality.
`max_items`	`int \| None`	`None`	Maximum cardinality (`None` = unbounded).
`required`	`bool`	`False`	Whether at least one item is required.

`get_pk_field_name`

get_pk_field_name(model_cls: type) -> str

Returns the Python attribute name for the primary key of a mapped SQLModel class. Falls back to "id" if inspection fails.

CRUD router

`create_crud_router`

create_crud_router(
    model_class: Type[T],
    *,
    prefix: str | None = None,
    tags: list[str] | None = None,
    pk_type: type = int,
) -> APIRouter

Generates a FastAPI APIRouter with standard list, get, create, update, and delete endpoints for model_class. See CRUD Router for the full endpoint reference.

model_class

Type[T]

required

A SQLModel table class.

prefix

str | None

URL prefix for all routes. Defaults to /<tablename>.

Access control

VeloIQ provides three layers of declarative access control. All are opt-in and can be combined freely.

Method set constants

Constant	Value	Description
`ALL_METHODS`	`{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"}`	All HTTP methods.
`WRITE_METHODS`	`{"GET", "POST", "PUT", "PATCH", "OPTIONS", "HEAD"}`	All methods except DELETE.
`READ_METHODS`	`{"GET", "OPTIONS", "HEAD"}`	Read-only methods.

`RoleDef`

@dataclass
class RoleDef:
    name: str
    methods: set[str]
    description: str = ""
    is_preset: bool = True

Defines a developer-declared role. Pass a list of RoleDef objects to VeloIQConfig.roles; they are upserted to the database on startup.

`DEFAULT_ROLES`

Built-in role definitions used when VeloIQConfig.roles is not overridden.

Name	Methods	Description
`Admin`	`ALL_METHODS`	Full administrative access.
`Manager`	`WRITE_METHODS`	Create, edit, and view — no delete.
`Viewer`	`READ_METHODS`	Read-only access.

`model_access`

@model_access(Manager=["list", "show"], Viewer=["list", "show"])
class Invoice(TimestampedModel, table=True):
    ...

Class decorator that restricts which Refine actions a role may perform on this specific model. Roles not mentioned inherit their global permissions unchanged. Exceptions are restrictive only — they can narrow access, never grant beyond a role’s global permissions.

`veloiq_field`

veloiq_field(
    *,
    read_roles: list[str] | None = None,
    write_roles: list[str] | None = None,
    **kwargs: Any,
) -> Any

SQLModel/Pydantic field with optional per-role read and write restrictions. Wraps pydantic.Field and stores role metadata in json_schema_extra so the schema generator emits readRoles/writeRoles into TypeScript schemas. The CRUD router enforces these restrictions at runtime.

read_roles

list[str] | None

Roles allowed to read this field. Absent means all roles can read it.

write_roles

list[str] | None

Roles allowed to write this field. Absent means all roles can write it.

**kwargs

Any

Passed through to pydantic.Field (e.g. default, description).

from veloiq_framework import veloiq_field, TimestampedModel

class Employee(TimestampedModel, table=True):
    __tablename__ = "employee"
    name: str
    department: str
    salary: float = veloiq_field(
        default=0.0,
        read_roles=["Admin"],
        write_roles=["Admin"],
    )
    notes: str = veloiq_field(
        default="",
        write_roles=["Admin", "Manager"],
    )

`rebac`

@rebac(
    *,
    filter=None,
    owner_field: str | None = None,
    tenant_field: str | None = None,
)

Class decorator for row-level access control. At least one of filter, owner_field, or tenant_field must be supplied. Multiple options are OR-combined — a row is visible if any rule allows it.

filter

callable | None

A lambda (user, cls, session) -> SQLAlchemy clause | True | False | None. Return a WHERE clause for permitted rows, True for no restriction, or False to deny all rows.

owner_field

str | None

Name of a column pointing to veloiq_user.id. Shorthand for a filter that matches cls.<field> == user["eid"].

tenant_field

str | None

Name of a column pointing to veloiq_tenant.id. Grants access when the tenant is one the authenticated user belongs to.

from veloiq_framework import rebac, TimestampedModel
from sqlmodel import Field

@rebac(owner_field="created_by")
class Note(TimestampedModel, table=True):
    created_by: int = Field(foreign_key="veloiq_user.id")

@rebac(tenant_field="tenant_id")
class Contract(TimestampedModel, table=True):
    tenant_id: int = Field(foreign_key="veloiq_tenant.id")

@rebac applies to all roles, including Admin. To exempt Admins, return True from the filter when the user has the Admin role. Inaccessible rows return 404, not 403, to avoid leaking which IDs exist.

`rebac_subquery`

rebac_subquery(model_class: type, user: dict, session) -> Subquery

Returns a SQLAlchemy subquery of primary keys of model_class rows that user may access. Designed to be called inside a @rebac(filter=…) lambda to express relationship-based access. The target model_class must itself carry a @rebac decorator. Raises ValueError on circular dependencies.

from veloiq_framework import rebac, rebac_subquery, TimestampedModel

@rebac(filter=lambda user, cls, session:
           cls.folder_id.in_(rebac_subquery(Folder, user, session)))
class Document(TimestampedModel, table=True):
    folder_id: int

Auth utilities

`get_current_user`

FastAPI dependency that returns the authenticated user payload decoded from the JWT Bearer token. The payload is a dict containing at minimum sub (user ID as string) and roles (list of role names).

from fastapi import Depends
from veloiq_framework import get_current_user

@router.get("/me")
def me(user=Depends(get_current_user)):
    return user

`require_role`

FastAPI dependency that raises HTTP 403 if the authenticated user does not hold at least one of the specified roles.

from fastapi import Depends
from veloiq_framework import require_role

@router.delete("/{id}")
def delete_item(id: int, _=Depends(require_role("Admin"))):
    ...

`get_session`

FastAPI dependency that yields a sqlmodel.Session bound to the configured database engine. Use it in custom endpoints that need direct database access.

from fastapi import Depends
from sqlmodel import Session, select
from veloiq_framework import get_session
from .models import Order

@router.get("/pending")
def list_pending(session: Session = Depends(get_session)):
    return session.exec(select(Order).where(Order.status == "pending")).all()

Configuration

Full VeloIQConfig field reference and environment variables.

CRUD Router

Auto-generated endpoint reference and query parameter details.

CLI

Python API

React UI Library

VeloIQ Python API: All Public Framework Exports

Installation

App factory

`create_veloiq_app`

Base models

`FrameworkModel`

`TimestampedModel`

`StandardModel`

Relationships

`jm_relationship`

`RelationCardinality`

`get_pk_field_name`

CRUD router

`create_crud_router`

Access control

Method set constants

`RoleDef`

`DEFAULT_ROLES`

`model_access`

`veloiq_field`

`rebac`

`rebac_subquery`

Auth utilities

`get_current_user`

`require_role`

`get_session`

Configuration

CRUD Router

​Installation

​App factory

​create_veloiq_app

​Base models

​FrameworkModel

​TimestampedModel

​StandardModel

​Relationships

​jm_relationship

​RelationCardinality

​get_pk_field_name

​CRUD router

​create_crud_router

​Access control

​Method set constants

​RoleDef

​DEFAULT_ROLES

​model_access

​veloiq_field

​rebac

​rebac_subquery

​Auth utilities

​get_current_user

​require_role

​get_session

Configuration

CRUD Router

Installation

App factory

`create_veloiq_app`

Base models

`FrameworkModel`

`TimestampedModel`

`StandardModel`

Relationships

`jm_relationship`

`RelationCardinality`

`get_pk_field_name`

CRUD router

`create_crud_router`

Access control

Method set constants

`RoleDef`

`DEFAULT_ROLES`

`model_access`

`veloiq_field`

`rebac`

`rebac_subquery`

Auth utilities

`get_current_user`

`require_role`

`get_session`