tigrbl 0.0.1.dev1__py3-none-any.whl → 0.3.0__py3-none-any.whl

tigrbl/README.md

@@ -0,0 +1,94 @@
+# Tigrbl v3 Engine Conformance
+
+Applications built on Tigrbl v3 **must** create database engines and sessions
+through the `tigrbl.engine` package. Direct imports from
+`sqlalchemy.ext.asyncio`—such as `AsyncSession`, `create_async_engine`, or
+`async_sessionmaker`—are **not permitted**.
+
+Instead, construct an engine via `Engine` or the helper `engine()` function:
+
+```python
+from tigrbl.engine import engine
+
+DB = engine("sqlite+aiosqlite:///./app.db")
+app = TigrblApp(engine=DB)
+```
+
+Use `DB.get_db` as the FastAPI dependency for acquiring sessions and avoid
+exporting custom `get_async_db` helpers.
+
+These rules apply to all first-party applications, including
+`tigrbl_kms`, `tigrbl_auth`, and the `peagen` gateway.
+
+## Column-Level Configuration
+
+Tigrbl v3 models declare their database and API behavior through
+`ColumnSpec` helpers exposed in `tigrbl.column`.  Use `acol` for
+persisted columns and `vcol` for wire-only virtual values.  Each column
+can combine three optional specs:
+
+- `S` (`StorageSpec`) – database shape such as types, keys, indexes, and
+  other SQLAlchemy column arguments.
+- `F` (`FieldSpec`) – Python and schema metadata including validation
+  constraints or example values.
+- `IO` (`IOSpec`) – inbound/outbound exposure settings, aliases,
+  sensitivity flags, and filtering/sorting capabilities.
+
+For a deeper look at these helpers, see [column/README.md](column/README.md).
+
+Example:
+
+```python
+from tigrbl.column import acol, vcol, F, S, IO
+
+class Widget(Base):
+    __tablename__ = "widgets"
+
+    id: Mapped[int] = acol(storage=S(primary_key=True))
+    name: Mapped[str] = acol(
+        field=F(constraints={"max_length": 50}),
+        storage=S(nullable=False, index=True),
+        io=IO(
+            in_verbs=("create", "update"),
+            out_verbs=("read", "list"),
+            sortable=True,
+        ),
+    )
+    checksum: Mapped[str] = vcol(
+        field=F(),
+        io=IO(out_verbs=("read",)),
+        read_producer=lambda obj, ctx: f"{obj.name}:{obj.id}",
+    )
+```
+
+Virtual columns like `checksum` use a `read_producer` (or `producer`)
+function to compute values on the fly.  Leveraging these specs keeps
+column behavior declarative and consistent across the ORM, schema
+generation, and runtime I/O.
+
+## 🧩 First-Class Object Pattern
+
+Tigrbl v3 organizes its core building blocks with a common structure:
+
+- 📄 **Spec** – declarative metadata describing behavior.
+- 🏛️ **Class** – runtime implementation of the object.
+- 🎀 **Decorators** – syntactic sugar for declaring features.
+- ⚡️ **Shortcuts** – handy constructors for common setups.
+
+Some objects also expose optional helpers:
+
+- 🫺 **Collect** – gathers declarations from a class hierarchy.
+- 🧩 **Resolver** – finalizes configuration from specs.
+- 🎧 **Builder** – assembles complex runtime resources.
+
+| Object | 📄 Spec | 🏛️ Class | 🎀 Decorators | ⚡️ Shortcuts | 🫺 Collect | 🧩 Resolver | 🎧 Builder |
+|--------|----------|-----------|----------------|----------------|----------------|----------------|----------------|
+| Column | `column_spec.py` | `_column.py` | — | `shortcuts.py` | `collect.py` | — | — |
+| Engine | `engine_spec.py` | `_engine.py` | `decorators.py` | `shortcuts.py` | `collect.py` | `resolver.py` | `builders.py` |
+| Op | `types.py` | `_op.py` | `decorators.py` | — | `collect.py` | — | — |
+| API | `api_spec.py` | `_api.py` | — | `shortcuts.py` | — | — | — |
+| App | `app_spec.py` | `_app.py` | — | `shortcuts.py` | — | — | — |
+| Table | `table_spec.py` | `_table.py` | — | `shortcuts.py` | — | — | — |
+
+This pattern keeps the system modular and predictable, making it easy to
+discover related modules for any given concept.

tigrbl/__init__.py

@@ -1,14 +1,139 @@
-from .ExampleAgent import ExampleAgent as ExampleAgent
-
-__version__ = "0.6.0.dev26"
-__long_desc__ = """
-
-# Swarmauri Example Plugin
-
-This repository includes an example of a Swarmauri Plugin.
-
-Visit us at: https://swarmauri.com
-Follow us at: https://github.com/swarmauri
-Star us at: https://github.com/swarmauri/swarmauri-sdk
-
-"""
+# tigrbl/__init__.py
+"""
+Tigrbl – public API
+
+OpSpec-centric building blocks to bind models, wire schemas/handlers/hooks,
+register RPC & REST, and (optionally) mount JSON-RPC and diagnostics.
+
+Quick start:
+    from tigrbl import include_model, build_jsonrpc_router, mount_diagnostics
+    from tigrbl import OpSpec, hook_ctx, op_ctx, alias_ctx, schema_ctx, SchemaRef
+
+    include_model(api, User, app=fastapi_app)
+    app.include_router(build_jsonrpc_router(api), prefix="/rpc")
+    app.include_router(mount_diagnostics(api), prefix="/system")
+
+    # Example: custom op using an existing schema
+    @op_ctx(alias="search", target="custom", arity="collection",
+            request_schema=SchemaRef("Search", "in"),
+            response_schema=SchemaRef("Search", "out"))
+    def search(cls, ctx):
+        ...
+"""
+
+from __future__ import annotations
+
+# ── OpSpec (source of truth) ───────────────────────────────────────────────────
+from .op import (
+    OpSpec,
+    get_registry,
+    # types and helpers re-exported from ops
+    TargetOp,
+    Arity,
+    PersistPolicy,
+    PHASE,
+    HookPhase,
+    PHASES,
+)
+from .schema.types import SchemaRef, SchemaArg
+
+# ── Ctx-only decorators (new surface; replaces legacy ops.decorators) ─────────
+
+from .op import alias_ctx, op_ctx, alias, op_alias
+from .hook import hook_ctx
+from .engine.decorators import engine_ctx
+from .schema.decorators import schema_ctx
+from .response.decorators import response_ctx
+from .response.types import ResponseSpec
+
+# ── Bindings (model + API orchestration) ───────────────────────────────────────
+from .bindings import (
+    bind,
+    rebind,
+    build_schemas,
+    build_hooks,
+    build_handlers,
+    register_rpc,
+    build_rest,
+    include_model,
+    include_models,
+    rpc_call,
+)
+
+# ── Runtime (advanced: run a phase pipeline directly) ──────────────────────────
+from .runtime.executor import _invoke
+
+# ── Schemas ────────────────────────────────────────────────────────────────────
+from .schema import _build_schema, _build_list_params, get_schema
+
+# ── Transport & Diagnostics (optional) ─────────────────────────────────────────
+from .transport.jsonrpc import build_jsonrpc_router
+from .system import mount_diagnostics
+
+# ── DB/bootstrap helpers (infra; optional) ─────────────────────────────────────
+from .ddl import ensure_schemas, register_sqlite_attach, bootstrap_dbschema
+
+# ── Config constants (defaults used by REST) ───────────────────────────────────
+from .config.constants import DEFAULT_HTTP_METHODS
+from .app.tigrbl_app import TigrblApp
+from .api import Api, TigrblApi
+
+from .table import Base
+from .op import Op
+from .app._app import App
+
+
+__all__: list[str] = []
+
+__all__ += ["TigrblApp", "TigrblApi", "Api", "Base", "App", "Op"]
+
+__all__ += [
+    # OpSpec core
+    "OpSpec",
+    "get_registry",
+    # types
+    "TargetOp",
+    "Arity",
+    "PersistPolicy",
+    "PHASE",
+    "PHASES",
+    "HookPhase",
+    "SchemaRef",
+    "SchemaArg",
+    # Ctx-only decorators
+    "alias_ctx",
+    "op_ctx",
+    "hook_ctx",
+    "schema_ctx",
+    "response_ctx",
+    "alias",
+    "op_alias",
+    "engine_ctx",
+    "ResponseSpec",
+    # Bindings
+    "bind",
+    "rebind",
+    "build_schemas",
+    "build_hooks",
+    "build_handlers",
+    "register_rpc",
+    "build_rest",
+    "include_model",
+    "include_models",
+    "rpc_call",
+    # Runtime
+    "_invoke",
+    # Schemas
+    "_build_schema",
+    "_build_list_params",
+    "get_schema",
+    # Transport / Diagnostics
+    "build_jsonrpc_router",
+    "mount_diagnostics",
+    # DB/infra
+    "ensure_schemas",
+    "register_sqlite_attach",
+    "bootstrap_dbschema",
+    # Config
+    "DEFAULT_HTTP_METHODS",
+]

tigrbl/api/__init__.py

@@ -0,0 +1,6 @@
+"""Core API surfaces for the Tigrbl package."""
+
+from ._api import Api
+from .tigrbl_api import TigrblApi
+
+__all__ = ["Api", "TigrblApi"]

tigrbl/api/_api.py

@@ -0,0 +1,97 @@
+# tigrbl/tigrbl/v3/api/_api.py
+from __future__ import annotations
+from typing import Any
+from types import SimpleNamespace
+
+from ..deps.fastapi import APIRouter as ApiRouter
+from ..engine.engine_spec import EngineCfg
+from ..engine import install_from_objects
+from ..ddl import initialize as _ddl_initialize
+from ..engine import resolver as _resolver
+from ..app._model_registry import initialize_model_registry
+from .api_spec import APISpec
+
+
+class Api(APISpec, ApiRouter):
+    """API router with model and table registries."""
+
+    MODELS: tuple[Any, ...] = ()
+    TABLES: tuple[Any, ...] = ()
+
+    # dataclass inheritance makes instances unhashable; use identity semantics
+    # for both hashing and equality so objects can participate in sets/dicts
+    def __hash__(self) -> int:  # pragma: no cover - simple identity hash
+        return id(self)
+
+    def __eq__(self, other: object) -> bool:  # pragma: no cover - identity compare
+        return self is other
+
+    def __init__(
+        self, *, engine: EngineCfg | None = None, **router_kwargs: Any
+    ) -> None:
+        # Manually initialize fields from ``APISpec`` so ``repr`` and other
+        # dataclass-generated helpers have the expected attributes, while also
+        # preparing mutable containers used at runtime.
+        self.name = getattr(self, "NAME", "api")
+        self.prefix = self.PREFIX
+        self.engine = engine if engine is not None else getattr(self, "ENGINE", None)
+        self.tags = list(getattr(self, "TAGS", []))
+        self.ops = tuple(getattr(self, "OPS", ()))
+        self.schemas = SimpleNamespace()
+        self.hooks = SimpleNamespace()
+        self.security_deps = tuple(getattr(self, "SECURITY_DEPS", ()))
+        self.deps = tuple(getattr(self, "DEPS", ()))
+        self.response = getattr(self, "RESPONSE", None)
+        # ``models`` is expected to be a dict at runtime for registry lookups.
+        self.models = initialize_model_registry(getattr(self, "MODELS", ()))
+
+        ApiRouter.__init__(
+            self,
+            prefix=self.PREFIX,
+            tags=self.tags,
+            dependencies=list(self.security_deps) + list(self.deps),
+            **router_kwargs,
+        )
+
+        # namespace containers
+        self.tables: dict[str, Any] = {}
+
+        _engine_ctx = engine if engine is not None else getattr(self, "ENGINE", None)
+        if _engine_ctx is not None:
+            _resolver.register_api(self, _engine_ctx)
+            _resolver.resolve_provider(api=self)
+
+    def install_engines(
+        self, *, api: Any = None, models: tuple[Any, ...] | None = None
+    ) -> None:
+        # If class declared APIS/MODELS, use them unless explicit args are passed.
+        apis = (api,) if api is not None else self.APIS
+        models = models if models is not None else self.MODELS
+        if apis:
+            for a in apis:
+                install_from_objects(app=self, api=a, models=models)
+        else:
+            install_from_objects(app=self, api=None, models=models)
+
+    def _collect_tables(self) -> list[Any]:
+        seen = set()
+        tables = []
+        for model in self.models.values():
+            if not hasattr(model, "__table__"):
+                try:  # pragma: no cover - defensive remap
+                    from ..table import Base
+                    from ..table._base import _materialize_colspecs_to_sqla
+
+                    _materialize_colspecs_to_sqla(model)
+                    Base.registry.map_declaratively(model)
+                except Exception:
+                    pass
+            table = getattr(model, "__table__", None)
+            if table is not None and not table.columns:
+                continue
+            if table is not None and table not in seen:
+                seen.add(table)
+                tables.append(table)
+        return tables
+
+    initialize = _ddl_initialize

tigrbl/api/api_spec.py

@@ -0,0 +1,30 @@
+# tigrbl/tigrbl/v3/api/api_spec.py
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Sequence
+from ..engine.engine_spec import EngineCfg
+from ..response.types import ResponseSpec
+
+
+@dataclass
+class APISpec:
+    """
+    Used to *produce an API subclass* via API.from_spec().
+    """
+
+    name: str = "api"
+    prefix: str = ""
+    engine: Optional[EngineCfg] = None
+    tags: Sequence[str] = field(default_factory=tuple)
+
+    # NEW
+    ops: Sequence[Any] = field(default_factory=tuple)
+    schemas: Sequence[Any] = field(default_factory=tuple)
+    hooks: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+    security_deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+    deps: Sequence[Callable[..., Any]] = field(default_factory=tuple)
+
+    response: Optional[ResponseSpec] = None
+
+    # optional: models this API exposes (auto-install)
+    models: Sequence[Any] = field(default_factory=tuple)

tigrbl/api/mro_collect.py

@@ -0,0 +1,43 @@
+# tigrbl/v3/api/mro_collect.py
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import Any, Callable, Dict, Iterable, Mapping
+
+from ..config.constants import TIGRBL_API_HOOKS_ATTR
+
+logger = logging.getLogger("uvicorn")
+
+
+@lru_cache(maxsize=None)
+def mro_collect_api_hooks(api: type) -> Dict[str, Dict[str, list[Callable[..., Any]]]]:
+    """Collect API-level hook declarations across ``api``'s MRO.
+
+    The accepted shape mirrors the hooks mapping used by the bindings:
+        {alias: {phase: Iterable[callable]}}
+    Hooks from base classes are merged with subclass definitions taking precedence.
+    """
+    logger.info("Collecting API hooks for %s", api.__name__)
+    out: Dict[str, Dict[str, list[Callable[..., Any]]]] = {}
+    for base in reversed(api.__mro__):
+        mapping = getattr(base, TIGRBL_API_HOOKS_ATTR, None)
+        if not isinstance(mapping, Mapping):
+            continue
+        for alias, phase_map in mapping.items():
+            bucket = out.setdefault(str(alias), {})
+            if not isinstance(phase_map, Mapping):
+                continue
+            for phase, items in phase_map.items():
+                lst = bucket.setdefault(str(phase), [])
+                if isinstance(items, Iterable):
+                    for fn in items:
+                        if callable(fn):
+                            lst.append(fn)
+                elif callable(items):
+                    lst.append(items)
+    logger.debug("Collected API hooks for aliases: %s", list(out.keys()))
+    return out
+
+
+__all__ = ["mro_collect_api_hooks"]

tigrbl/api/shortcuts.py

@@ -0,0 +1,56 @@
+# tigrbl/tigrbl/v3/api/shortcuts.py
+from __future__ import annotations
+
+from typing import Any, Sequence, Type
+
+from .api_spec import APISpec
+from ._api import Api
+
+
+def defineApiSpec(
+    *,
+    # identity
+    name: str = "api",
+    prefix: str = "",
+    tags: Sequence[str] = (),
+    # engine
+    engine: Any = None,
+    # composition
+    ops: Sequence[Any] = (),
+    schemas: Sequence[Any] = (),
+    hooks: Sequence[Any] = (),
+    security_deps: Sequence[Any] = (),
+    deps: Sequence[Any] = (),
+    models: Sequence[Any] = (),
+) -> Type[APISpec]:
+    """
+    Build an API-spec class with class attributes only (no instances).
+    Use it directly in your class MRO:
+
+        class TenantA(defineApiSpec(name="tenantA", engine=...)):
+            pass
+
+    or pass it to `deriveApi(...)` to get a concrete API subclass.
+    """
+    attrs = dict(
+        NAME=name,
+        PREFIX=prefix,
+        TAGS=tuple(tags or ()),
+        ENGINE=engine,
+        OPS=tuple(ops or ()),
+        SCHEMAS=tuple(schemas or ()),
+        HOOKS=tuple(hooks or ()),
+        SECURITY_DEPS=tuple(security_deps or ()),
+        DEPS=tuple(deps or ()),
+        MODELS=tuple(models or ()),
+    )
+    return type("APISpec", (APISpec,), attrs)
+
+
+def deriveApi(**kw: Any) -> Type[Api]:
+    """Produce a concrete :class:`Api` subclass that inherits the spec."""
+    Spec = defineApiSpec(**kw)
+    return type("APIWithSpec", (Spec, Api), {})
+
+
+__all__ = ["defineApiSpec", "deriveApi"]