pre-alpha

Concepts

Use other libraries

implemented Updated November 20, 2026 2 min read

Hinoki has its own Schema and Model classes. It does not accept Pydantic, SQLAlchemy or Django models as request bodies, responses or tables. This page says why, what that costs, and which extension points exist today.

Why the framework owns them

  • One declaration feeds every output. Request binding, the response check, OpenAPI, application MCP, the admin and rules read the same Schema and Model classes, so they can promise the same contract.
  • The hot paths are native. Routing, selected request parsing and ORM execution run in Rust against Hinoki's own declarations, without calling back into a validation library or a foreign ORM per request.
  • Rules need known structure. "A response Schema never exposes password_hash" is checkable because the Schema is an inspectable Hinoki class.

What this costs

  • A library that expects its own model type does not plug in: a Pydantic-based SDK, a SQLAlchemy extension or a Django app cannot be given a Hinoki Model or Schema.
  • There is no adapter from SQLAlchemy, Django or Pydantic models, and no plugin system.
  • Databases are SQLite, PostgreSQL, MySQL and MariaDB through Hinoki's own drivers; another ORM's connections are not shared with its pool.

Bring a library anyway

Anything that works on plain Python data works with Hinoki. Schema.to_dict() and Schema.dump() return plain data, and a Schema is built from plain values:

# notes/apps/quotes/api.py
from hinoki import Schema, http

from notes.apps.quotes.client import fetch_quote  # any library returning plain data


class Quote(Schema):
    symbol: str
    price: float


@http.get("/{symbol}", access=None)
async def quote(symbol: str) -> Quote:
    raw = await fetch_quote(symbol)
    return Quote(symbol=raw["symbol"], price=raw["price"])

Keep the translation at the edge of the handler, and keep a second store's connections in a module so their lifetime follows the worker. Hinoki does not time-box what that code does.

Extension points

You want to Use Guide
Add an authentication scheme Subclass BearerAuth, APIKeyAuth or HeaderAuth Authentication
Reuse a permission rule A typed Access policy Authentication
Accept or answer another body format A parser or renderer Parsers and renderers
Translate a library's exception app.error_handler(Kind) Errors
Own a resource per worker A module with ctx.provide and ctx.get, or a DatabaseModule subclass Modules
Enforce a team convention Subclass hinoki.rules.Rule Rules
Add typed configuration settings.AppSettings Settings
Ship routes in a package Anything a routes list accepts: a function, a RouteGroup, an API class, a Mount, or an object with an api() method Register routes
Expose actions to an agent expose_as_mcp with an allowlist Expose actions over MCP
Add metrics, tracing or other cross-cutting behaviour Wrap the ASGI application Serving
Run where only WSGI is available WSGIAdapter Serving

Cross-cutting behaviour around an action belongs in a middleware, which behaves the same on Kiso and Granian. An ASGI wrapper still works on Granian and sees the request before and after Hinoki. To run another web application next to Hinoki, put it behind the same reverse proxy or dispatch by path in your own ASGI code.

See also