telamon 0.1.0a0__tar.gz

telamon-0.1.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 z.nurym
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telamon-0.1.0a0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: telamon
+Version: 0.1.0a0
+Summary: Framework-agnostic admin panel for Python: SQLAlchemy, Tortoise ORM, MongoDB and Beanie, with a built-in React UI
+Keywords: admin,admin-panel,fastapi,starlette,sqlalchemy,tortoise-orm,mongodb,beanie
+Author: z.nurym
+Author-email: z.nurym <z.nurym@mycar.kz>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=4.0
+Requires-Dist: telamon[beanie,fastapi,mongo,sqlalchemy,tortoise] ; extra == 'all'
+Requires-Dist: beanie>=1.26 ; extra == 'beanie'
+Requires-Dist: fastapi>=0.110 ; extra == 'fastapi'
+Requires-Dist: pymongo>=4.9 ; extra == 'mongo'
+Requires-Dist: sqlalchemy>=2.0 ; extra == 'sqlalchemy'
+Requires-Dist: python-multipart>=0.0.9 ; extra == 'starlette'
+Requires-Dist: starlette>=0.37 ; extra == 'starlette'
+Requires-Dist: tortoise-orm>=0.21 ; extra == 'tortoise'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/znurym/telamon
+Project-URL: Repository, https://github.com/znurym/telamon
+Project-URL: Issues, https://github.com/znurym/telamon/issues
+Provides-Extra: all
+Provides-Extra: beanie
+Provides-Extra: fastapi
+Provides-Extra: mongo
+Provides-Extra: sqlalchemy
+Provides-Extra: starlette
+Provides-Extra: tortoise
+Description-Content-Type: text/markdown
+
+# Telamon Admin
+
+Framework‑agnostic admin panel for Python: a headless core with a JSON API, pluggable data
+backends (SQLAlchemy sync/async, Tortoise ORM, MongoDB via PyMongo/Motor, Beanie ODM) and thin
+transports (Starlette/FastAPI today; Flask and Django next). Ships with a built‑in React UI, no
+Node required at install time.
+
+> Status: pre‑alpha. API may change.
+
+## Quickstart (FastAPI + SQLAlchemy)
+
+```bash
+uv add "telamon[fastapi,sqlalchemy]"
+```
+
+```python
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from telamon import AdminSite, ModelAdmin, SimpleAuth, action
+from telamon.backends.sqlalchemy import SQLAlchemyBackend
+from telamon.transports.starlette import mount
+
+engine = create_async_engine("sqlite+aiosqlite:///app.db")
+site = AdminSite("My Admin", backend=SQLAlchemyBackend(engine),
+                 auth=SimpleAuth("change-me", {"admin": "admin"}))
+
+@site.register(Post)
+class PostAdmin(ModelAdmin):
+    list_display = ["id", "title", "status", "author"]
+    list_filter = ["status", "author", "tags"]
+    search_fields = ["title", "body"]
+    ordering = ["-id"]
+
+    @action("Publish", confirm="Publish selected posts?")
+    async def publish(self, request, objs):
+        repo = self.site.resource("post").repository
+        for post in objs:
+            await repo.update(post, {"status": "published"})
+        return f"Published {len(objs)} post(s)"
+
+app = FastAPI()
+mount(app, site, path="/admin")
+```
+
+## Backends
+
+| Backend | Install | Usage |
+|---|---|---|
+| SQLAlchemy 2.x, sync or async | `telamon[sqlalchemy]` | `SQLAlchemyBackend(engine_or_sessionmaker)` |
+| Tortoise ORM | `telamon[tortoise]` | `TortoiseBackend()`; run `Tortoise.init()` in your lifespan |
+| MongoDB (PyMongo sync, PyMongo async, Motor) | `telamon[mongo]` | `MongoBackend(client["db"])`, models are Pydantic classes |
+| Beanie ODM | `telamon[beanie]` | `BeanieBackend()`; run `init_beanie()` in your lifespan |
+
+MongoDB models are plain Pydantic classes; references are declared with `Ref`:
+
+```python
+from typing import Annotated
+from telamon.backends.mongo import MongoBackend, Ref
+
+class Order(BaseModel):
+    id: str                                              # maps to _id (ObjectId hex, int or str)
+    number: str = Field(max_length=20)
+    customer: Annotated[str | None, Ref(Customer)] = None   # many_to_one
+    tags: Annotated[list[str], Ref(Tag)] = []                # many_to_many
+```
+
+With Beanie, `Link[T]`, `list[Link[T]]` and `BackLink[T]` are picked up automatically and links are
+stored as DBRefs, so documents written by the admin load through Beanie unchanged.
+
+Runnable examples live in `examples/`:
+
+```bash
+uv run uvicorn examples.fastapi_sqlalchemy.app:app --reload        # async SQLAlchemy + SQLite
+uv run uvicorn examples.fastapi_sqlalchemy_sync.app:app --reload   # sync engine
+uv run uvicorn examples.fastapi_tortoise.app:app --reload
+docker run -d --rm -p 27017:27017 --name mongo mongo:7
+uv run uvicorn examples.fastapi_mongo.app:app --reload             # PyMongo async
+uv run uvicorn examples.fastapi_beanie.app:app --reload
+# open http://127.0.0.1:8000/admin  (admin / admin)
+```
+
+## Architecture
+
+```
+transports/   Starlette ──┐
+              Flask   (planned)  ──►  core/ (AdminSite, ModelAdmin, schema, filters, auth)
+              Django  (planned)  ──┘        ▲
+                                            │ Repository / Backend protocols
+backends/     sqlalchemy, tortoise, mongo, beanie, memory ─┘
+ui/           React SPA, built into src/telamon/static
+```
+
+* **core** never imports a web framework or an ORM. It exposes `AdminSite.dispatch(AdminRequest)`.
+* **backends** implement `Backend.introspect(model)` → `ModelSchema` and the async `Repository`
+  contract (`list`, `count`, `get`, `get_many`, `create`, `update`, `delete`, `to_dict`).
+* **transports** map framework requests to `AdminRequest` and serve the UI.
+
+### JSON API
+
+| Method | Path | |
+|---|---|---|
+| GET | `/_api/site` | resources, current user |
+| POST/GET | `/_api/auth/login`, `/_api/auth/logout`, `/_api/auth/me` | session auth |
+| GET | `/_api/{resource}/schema` | fields, actions, permissions |
+| GET | `/_api/{resource}?offset&limit&sort=-id,name&search=&filters=<json>` | list |
+| POST / GET / PATCH / DELETE | `/_api/{resource}`, `/_api/{resource}/{pk}` | CRUD |
+| DELETE | `/_api/{resource}` body `{"pks": [...]}` | bulk delete |
+| POST | `/_api/{resource}/actions/{name}` body `{"pks": [...]}` | custom action |
+| GET | `/_api/{resource}/options?q=` | autocomplete for relations |
+| GET | `/_api/{resource}/export?format=csv\|json` | export current view |
+
+Filter tree: `{"and": [{"field": "age", "op": "gte", "value": 18}, {"or": [...]}]}` with ops
+`eq ne lt lte gt gte in not_in contains icontains startswith endswith is_null between`.
+
+## Development
+
+```bash
+uv sync --all-extras          # python deps
+uv run pytest                 # core + backend contract tests + transport tests
+docker run -d --rm -p 27017:27017 mongo:7   # Mongo/Beanie tests skip when no server is reachable
+uv run ruff check src tests
+pnpm --dir ui install && pnpm --dir ui build   # rebuilds src/telamon/static
+pnpm --dir ui dev             # UI dev server, proxies /admin/_api to :8000
+```
+
+See `docs/PLAN.md` for the roadmap.

telamon-0.1.0a0/README.md

@@ -0,0 +1,127 @@
+# Telamon Admin
+
+Framework‑agnostic admin panel for Python: a headless core with a JSON API, pluggable data
+backends (SQLAlchemy sync/async, Tortoise ORM, MongoDB via PyMongo/Motor, Beanie ODM) and thin
+transports (Starlette/FastAPI today; Flask and Django next). Ships with a built‑in React UI, no
+Node required at install time.
+
+> Status: pre‑alpha. API may change.
+
+## Quickstart (FastAPI + SQLAlchemy)
+
+```bash
+uv add "telamon[fastapi,sqlalchemy]"
+```
+
+```python
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from telamon import AdminSite, ModelAdmin, SimpleAuth, action
+from telamon.backends.sqlalchemy import SQLAlchemyBackend
+from telamon.transports.starlette import mount
+
+engine = create_async_engine("sqlite+aiosqlite:///app.db")
+site = AdminSite("My Admin", backend=SQLAlchemyBackend(engine),
+                 auth=SimpleAuth("change-me", {"admin": "admin"}))
+
+@site.register(Post)
+class PostAdmin(ModelAdmin):
+    list_display = ["id", "title", "status", "author"]
+    list_filter = ["status", "author", "tags"]
+    search_fields = ["title", "body"]
+    ordering = ["-id"]
+
+    @action("Publish", confirm="Publish selected posts?")
+    async def publish(self, request, objs):
+        repo = self.site.resource("post").repository
+        for post in objs:
+            await repo.update(post, {"status": "published"})
+        return f"Published {len(objs)} post(s)"
+
+app = FastAPI()
+mount(app, site, path="/admin")
+```
+
+## Backends
+
+| Backend | Install | Usage |
+|---|---|---|
+| SQLAlchemy 2.x, sync or async | `telamon[sqlalchemy]` | `SQLAlchemyBackend(engine_or_sessionmaker)` |
+| Tortoise ORM | `telamon[tortoise]` | `TortoiseBackend()`; run `Tortoise.init()` in your lifespan |
+| MongoDB (PyMongo sync, PyMongo async, Motor) | `telamon[mongo]` | `MongoBackend(client["db"])`, models are Pydantic classes |
+| Beanie ODM | `telamon[beanie]` | `BeanieBackend()`; run `init_beanie()` in your lifespan |
+
+MongoDB models are plain Pydantic classes; references are declared with `Ref`:
+
+```python
+from typing import Annotated
+from telamon.backends.mongo import MongoBackend, Ref
+
+class Order(BaseModel):
+    id: str                                              # maps to _id (ObjectId hex, int or str)
+    number: str = Field(max_length=20)
+    customer: Annotated[str | None, Ref(Customer)] = None   # many_to_one
+    tags: Annotated[list[str], Ref(Tag)] = []                # many_to_many
+```
+
+With Beanie, `Link[T]`, `list[Link[T]]` and `BackLink[T]` are picked up automatically and links are
+stored as DBRefs, so documents written by the admin load through Beanie unchanged.
+
+Runnable examples live in `examples/`:
+
+```bash
+uv run uvicorn examples.fastapi_sqlalchemy.app:app --reload        # async SQLAlchemy + SQLite
+uv run uvicorn examples.fastapi_sqlalchemy_sync.app:app --reload   # sync engine
+uv run uvicorn examples.fastapi_tortoise.app:app --reload
+docker run -d --rm -p 27017:27017 --name mongo mongo:7
+uv run uvicorn examples.fastapi_mongo.app:app --reload             # PyMongo async
+uv run uvicorn examples.fastapi_beanie.app:app --reload
+# open http://127.0.0.1:8000/admin  (admin / admin)
+```
+
+## Architecture
+
+```
+transports/   Starlette ──┐
+              Flask   (planned)  ──►  core/ (AdminSite, ModelAdmin, schema, filters, auth)
+              Django  (planned)  ──┘        ▲
+                                            │ Repository / Backend protocols
+backends/     sqlalchemy, tortoise, mongo, beanie, memory ─┘
+ui/           React SPA, built into src/telamon/static
+```
+
+* **core** never imports a web framework or an ORM. It exposes `AdminSite.dispatch(AdminRequest)`.
+* **backends** implement `Backend.introspect(model)` → `ModelSchema` and the async `Repository`
+  contract (`list`, `count`, `get`, `get_many`, `create`, `update`, `delete`, `to_dict`).
+* **transports** map framework requests to `AdminRequest` and serve the UI.
+
+### JSON API
+
+| Method | Path | |
+|---|---|---|
+| GET | `/_api/site` | resources, current user |
+| POST/GET | `/_api/auth/login`, `/_api/auth/logout`, `/_api/auth/me` | session auth |
+| GET | `/_api/{resource}/schema` | fields, actions, permissions |
+| GET | `/_api/{resource}?offset&limit&sort=-id,name&search=&filters=<json>` | list |
+| POST / GET / PATCH / DELETE | `/_api/{resource}`, `/_api/{resource}/{pk}` | CRUD |
+| DELETE | `/_api/{resource}` body `{"pks": [...]}` | bulk delete |
+| POST | `/_api/{resource}/actions/{name}` body `{"pks": [...]}` | custom action |
+| GET | `/_api/{resource}/options?q=` | autocomplete for relations |
+| GET | `/_api/{resource}/export?format=csv\|json` | export current view |
+
+Filter tree: `{"and": [{"field": "age", "op": "gte", "value": 18}, {"or": [...]}]}` with ops
+`eq ne lt lte gt gte in not_in contains icontains startswith endswith is_null between`.
+
+## Development
+
+```bash
+uv sync --all-extras          # python deps
+uv run pytest                 # core + backend contract tests + transport tests
+docker run -d --rm -p 27017:27017 mongo:7   # Mongo/Beanie tests skip when no server is reachable
+uv run ruff check src tests
+pnpm --dir ui install && pnpm --dir ui build   # rebuilds src/telamon/static
+pnpm --dir ui dev             # UI dev server, proxies /admin/_api to :8000
+```
+
+See `docs/PLAN.md` for the roadmap.

telamon-0.1.0a0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "telamon"
+version = "0.1.0a0"
+description = "Framework-agnostic admin panel for Python: SQLAlchemy, Tortoise ORM, MongoDB and Beanie, with a built-in React UI"
+readme = "README.md"
+authors = [
+    { name = "z.nurym", email = "z.nurym@mycar.kz" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["admin", "admin-panel", "fastapi", "starlette", "sqlalchemy", "tortoise-orm", "mongodb", "beanie"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: FastAPI",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "anyio>=4.0",
+]
+
+[project.optional-dependencies]
+sqlalchemy = [
+    "sqlalchemy>=2.0",
+]
+tortoise = [
+    "tortoise-orm>=0.21",
+]
+starlette = [
+    "python-multipart>=0.0.9",
+    "starlette>=0.37",
+]
+fastapi = [
+    "fastapi>=0.110",
+]
+mongo = [
+    "pymongo>=4.9",
+]
+beanie = [
+    "beanie>=1.26",
+]
+all = [
+    "telamon[beanie,fastapi,mongo,sqlalchemy,tortoise]",
+]
+
+[project.urls]
+Homepage = "https://github.com/znurym/telamon"
+Repository = "https://github.com/znurym/telamon"
+Issues = "https://github.com/znurym/telamon/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.27,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "aiosqlite>=0.22.1",
+    "beanie>=2.2.0",
+    "fastapi>=0.156.8",
+    "httpx>=0.28.1",
+    "mongomock>=4.3.0",
+    "motor>=3.7.1",
+    "mypy>=2.4.0",
+    "pymongo>=4.19.0",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "python-multipart>=0.0.32",
+    "ruff>=0.17.1",
+    "sqlalchemy[asyncio]>=2.0",
+    "tortoise-orm>=1.1.9",
+    "uvicorn>=0.54.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.uv.sources]
+telamon = { workspace = true }
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]

telamon-0.1.0a0/src/telamon/__init__.py

@@ -0,0 +1,51 @@
+"""Telamon Admin: framework-agnostic admin panel for SQLAlchemy and Tortoise ORM."""
+
+from .core import (
+    Action,
+    AdminError,
+    AdminRequest,
+    AdminResponse,
+    AdminSite,
+    AuthProvider,
+    Backend,
+    FieldType,
+    FilterGroup,
+    ListQuery,
+    ModelAdmin,
+    ModelSchema,
+    NotFound,
+    PermissionDenied,
+    Repository,
+    SessionAuth,
+    SimpleAuth,
+    User,
+    ValidationError,
+    action,
+    hash_password,
+)
+
+__version__ = "0.1.0a0"
+
+__all__ = [
+    "Action",
+    "AdminError",
+    "AdminRequest",
+    "AdminResponse",
+    "AdminSite",
+    "AuthProvider",
+    "Backend",
+    "FieldType",
+    "FilterGroup",
+    "ListQuery",
+    "ModelAdmin",
+    "ModelSchema",
+    "NotFound",
+    "PermissionDenied",
+    "Repository",
+    "SessionAuth",
+    "SimpleAuth",
+    "User",
+    "ValidationError",
+    "action",
+    "hash_password",
+]

telamon-0.1.0a0/src/telamon/backends/beanie/__init__.py

@@ -0,0 +1,3 @@
+from .backend import BeanieBackend, BeanieRepository
+
+__all__ = ["BeanieBackend", "BeanieRepository"]

telamon-0.1.0a0/src/telamon/backends/beanie/backend.py

@@ -0,0 +1,147 @@
+"""Beanie ODM backend. ``Link[T]`` -> many_to_one, ``list[Link[T]]`` -> many_to_many,
+``BackLink[T]`` -> one_to_many (read-only). Requires ``init_beanie()`` before the first request.
+
+Documents are read and written through the raw pymongo collection that Beanie manages; links are
+stored as DBRefs exactly as Beanie stores them, so both sides stay compatible.
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any, cast, get_args, get_origin
+
+from beanie import Document
+from beanie.odm.fields import BackLink, Link
+from bson import DBRef
+
+from telamon.core.model_admin import ModelAdmin
+from telamon.core.schema import FieldSchema, FieldType, ModelSchema, Relation
+
+from ..mongo.backend import Driver, MongoBackend, MongoRepository
+from ..mongo.common import Ref, _unwrap, field_from_annotation, parse_pk
+
+_HIDDEN = {"revision_id"}
+
+
+class BeanieBackend(MongoBackend):
+    name = "beanie"
+
+    def __init__(self) -> None:  # database comes from init_beanie()
+        self._driver: Driver | None = None
+
+    @property
+    def driver(self) -> Driver:
+        if self._driver is None:
+            raise RuntimeError(
+                "Beanie is not initialised; call init_beanie() before using the admin"
+            )
+        return self._driver
+
+    @driver.setter
+    def driver(self, value: Driver) -> None:
+        self._driver = value
+
+    def supports(self, model: type) -> bool:
+        return isinstance(model, type) and issubclass(model, Document)
+
+    def introspect(self, model: type, admin: ModelAdmin) -> ModelSchema:
+        fields: list[FieldSchema] = []
+        doc = cast(type[Document], model)
+        for name, info in doc.model_fields.items():
+            if name in _HIDDEN:
+                continue
+            if name == "id":
+                f = field_from_annotation("id", info.annotation, info)
+                f.primary_key, f.read_only, f.has_default, f.required, f.nullable = (
+                    True,
+                    True,
+                    True,
+                    False,
+                    False,
+                )
+                fields.insert(0, f)
+                continue
+            core, nullable, _ = _unwrap(info.annotation)
+            origin = get_origin(core)
+            inner = get_args(core)[0] if origin in (list, set, tuple) and get_args(core) else None
+            if origin is Link:
+                target = get_args(core)[0]
+                ann: Any = (str | None) if nullable else str
+                fields.append(field_from_annotation(name, ann, info, extra_metadata=[Ref(target)]))
+            elif inner is not None and get_origin(inner) is Link:
+                target = get_args(inner)[0]
+                fields.append(
+                    field_from_annotation(name, list[str], info, extra_metadata=[Ref(target)])
+                )
+            elif origin is BackLink or (inner is not None and get_origin(inner) is BackLink):
+                link = core if origin is BackLink else inner
+                target = get_args(link)[0] if get_args(link) else Any
+                fields.append(
+                    FieldSchema(
+                        name,
+                        FieldType.ONE_TO_MANY,
+                        read_only=True,
+                        relation=Relation(model=target, kind=FieldType.ONE_TO_MANY),
+                        sortable=False,
+                        filterable=False,
+                    )
+                )
+            else:
+                fields.append(field_from_annotation(name, info.annotation, info))
+        label = model.__name__
+        return ModelSchema(
+            key=label.lower(), label=label, label_plural=f"{label}s", pk_field="id", fields=fields
+        )
+
+    def repository(self, model: type, schema: ModelSchema, admin: ModelAdmin) -> BeanieRepository:
+        return BeanieRepository(self, model, schema, admin)
+
+
+class BeanieRepository(MongoRepository):
+    id_path = ".$id"
+
+    @property
+    def driver(self) -> Driver:
+        _ = self.coll  # resolving the collection also wires the driver from init_beanie()
+        return self.backend.driver
+
+    @property
+    def coll(self) -> Any:
+        if self._coll is None:
+            doc = cast(type[Document], self.model)
+            self._coll = doc.get_pymongo_collection()  # raises if init_beanie() was not run
+            self.backend.driver = Driver(self._coll.database)
+        return self._coll
+
+    @property
+    def collection_name(self) -> str:
+        return str(cast(type[Document], self.model).get_collection_name())
+
+    def _target_collection(self, f: FieldSchema) -> str:
+        assert f.relation is not None
+        return str(f.relation.model.get_collection_name())
+
+    def _rel_value(self, f: FieldSchema, value: Any) -> Any:
+        if value is None:
+            return None
+        coll = self._target_collection(f)
+        if f.type == FieldType.MANY_TO_MANY:
+            return [DBRef(coll, parse_pk(v)) for v in value]
+        return DBRef(coll, parse_pk(value))
+
+    def _rel_ids(self, f: FieldSchema, stored: Any) -> builtins.list[Any]:
+        if stored is None:
+            return []
+        items = stored if isinstance(stored, list) else [stored]
+        out = []
+        for i in items:
+            if isinstance(i, DBRef):
+                out.append(i.id)
+            elif isinstance(i, dict) and "$id" in i:
+                out.append(i["$id"])
+            else:
+                out.append(i)
+        return out
+
+
+__all__ = ["BeanieBackend", "BeanieRepository"]