dataenginex 1.0.0__tar.gz → 1.0.2__tar.gz

{dataenginex-1.0.0 → dataenginex-1.0.2}/.gitignore

@@ -90,3 +90,4 @@ Notes.txt
 
 # AI Coding Assistant
 .continue/
+.playwright-mcp/

{dataenginex-1.0.0 → dataenginex-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataenginex
-Version: 1.0.0
+Version: 1.0.2
 Summary: DataEngineX - Core framework for AI/ML/Data engineering projects
 Author-email: Jay <jayapal.myaka99@gmail.com>
 License: MIT License
@@ -26,28 +26,33 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Requires-Python: >=3.13
-Requires-Dist: click>=8.3.1
-Requires-Dist: croniter>=6.0.0
-Requires-Dist: duckdb>=1.5.0
+Requires-Dist: click>=8.3.2
+Requires-Dist: croniter>=6.2.2
+Requires-Dist: duckdb>=1.5.2
 Requires-Dist: email-validator>=2.3.0
-Requires-Dist: fastapi>=0.135.1
-Requires-Dist: httpx>=0.28.0
-Requires-Dist: opentelemetry-api>=1.40.0
-Requires-Dist: opentelemetry-exporter-otlp>=1.40.0
-Requires-Dist: opentelemetry-instrumentation-fastapi>=0.61b0
-Requires-Dist: opentelemetry-sdk>=1.40.0
-Requires-Dist: prometheus-client>=0.24.1
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: opentelemetry-api>=1.41.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.41.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.62b0
+Requires-Dist: opentelemetry-sdk>=1.41.0
+Requires-Dist: prometheus-client>=0.25.0
 Requires-Dist: pyarrow>=23.0.1
-Requires-Dist: pydantic>=2.10.0
-Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pydantic>=2.13.2
+Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: rich>=14.3.3
+Requires-Dist: rich>=15.0.0
 Requires-Dist: structlog>=25.5.0
-Requires-Dist: uvicorn>=0.42.0
+Requires-Dist: uvicorn>=0.44.0
+Provides-Extra: auth
+Requires-Dist: ldap3>=2.9.1; extra == 'auth'
+Requires-Dist: pyjwt[crypto]>=2.9.0; extra == 'auth'
 Provides-Extra: cloud
 Requires-Dist: boto3>=1.42.0; extra == 'cloud'
 Requires-Dist: google-cloud-bigquery>=3.40.0; extra == 'cloud'
 Requires-Dist: google-cloud-storage>=3.0.0; extra == 'cloud'
+Provides-Extra: observability
+Requires-Dist: langfuse>=4.3.1; extra == 'observability'
 Description-Content-Type: text/markdown
 
 # dataenginex

{dataenginex-1.0.0 → dataenginex-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dataenginex"
-version = "1.0.0"
+version = "1.0.2"
 description = "DataEngineX - Core framework for AI/ML/Data engineering projects"
 authors = [
     {name = "Jay", email = "jayapal.myaka99@gmail.com"}
@@ -9,24 +9,24 @@ readme = "src/dataenginex/README.md"
 requires-python = ">=3.13"
 license = {file = "LICENSE"}
 dependencies = [
-    "pydantic>=2.10.0",
-    "python-dotenv>=1.2.1",
+    "pydantic>=2.13.2",
+    "python-dotenv>=1.2.2",
     "pyyaml>=6.0.3",
-    "click>=8.3.1",
-    "rich>=14.3.3",
-    "duckdb>=1.5.0",
-    "croniter>=6.0.0",
-    "httpx>=0.28.0",
-    "prometheus-client>=0.24.1",
+    "click>=8.3.2",
+    "rich>=15.0.0",
+    "duckdb>=1.5.2",
+    "croniter>=6.2.2",
+    "httpx>=0.28.1",
+    "prometheus-client>=0.25.0",
     # API framework
-    "fastapi>=0.135.1",
-    "uvicorn>=0.42.0",
+    "fastapi>=0.136.0",
+    "uvicorn>=0.44.0",
     "structlog>=25.5.0",
     # OpenTelemetry
-    "opentelemetry-api>=1.40.0",
-    "opentelemetry-sdk>=1.40.0",
-    "opentelemetry-instrumentation-fastapi>=0.61b0",
-    "opentelemetry-exporter-otlp>=1.40.0",
+    "opentelemetry-api>=1.41.0",
+    "opentelemetry-sdk>=1.41.0",
+    "opentelemetry-instrumentation-fastapi>=0.62b0",
+    "opentelemetry-exporter-otlp>=1.41.0",
     "email-validator>=2.3.0",
     # Data formats
     "pyarrow>=23.0.1",
@@ -41,22 +41,36 @@ cloud = [
     "google-cloud-storage>=3.0.0",
     "google-cloud-bigquery>=3.40.0",
 ]
+auth = [
+    "pyjwt[crypto]>=2.9.0",
+    "ldap3>=2.9.1",
+]
+# NOTE: litellm is NOT declared here because it pins python-dotenv==1.0.1, which
+# conflicts with our python-dotenv>=1.2.1. Install separately for LiteLLMProvider:
+#     pip install 'litellm>=1.83.3' --no-deps
+# or manage via a dedicated venv. The provider is lazy-imported; DEX runs fine
+# without it.
+observability = [
+    "langfuse>=4.3.1",
+]
 
 [dependency-groups]
 dev = [
-    "pytest>=9.0.2",
-    "pytest-cov>=7.0.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
     "pytest-asyncio>=1.3.0",
-    "ruff>=0.15.6",
-    "mypy>=1.19.1",
+    "ruff>=0.15.11",
+    "mypy>=1.20.1",
     "types-pyyaml>=6.0.12.20250915",
     "types-requests>=2.32.4.20260107",
-    "poethepoet>=0.42.1",
-    "uv>=0.10.0",
-    "mkdocs-material>=9.7.0",
-    "mkdocstrings[python]>=0.29.0",
+    "poethepoet>=0.44.0",
+    "uv>=0.11.6",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
     "pre-commit>=4.5.1",
     "pip-audit>=2.10.0",
+    "pyjwt[crypto]>=2.12.1",
+    "cryptography>=46.0.7",
 ]
 data = [
     "pyspark>=4.1.1",
@@ -141,6 +155,10 @@ ignore_missing_imports = true
 module = ["sentence_transformers.*"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = ["litellm.*", "langfuse.*", "ldap3.*"]
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = ["pyspark.*"]
 ignore_missing_imports = true
@@ -169,6 +187,8 @@ filterwarnings = [
     "error",                                          # Treat all warnings as errors by default
     "ignore::DeprecationWarning:websockets\\.legacy",  # uvicorn uses deprecated websockets.legacy API
     "ignore::DeprecationWarning:uvicorn\\.protocols",  # uvicorn imports deprecated WebSocketServerProtocol
+    "ignore:unclosed.*socket:ResourceWarning",         # Starlette TestClient GC timing
+    "ignore:unclosed event loop:ResourceWarning",      # Starlette TestClient GC timing
 ]
 
 [tool.coverage.run]

{dataenginex-1.0.0 → dataenginex-1.0.2}/src/dataenginex/ai/agents/builtin.py

@@ -17,6 +17,10 @@ from dataenginex.ai.agents import agent_registry
 from dataenginex.ai.tools import ToolRegistry, tool_registry
 from dataenginex.ai.tools.builtin import register_builtin_tools
 from dataenginex.core.interfaces import BaseAgentRuntime
+from dataenginex.middleware.domain_metrics import (
+    ai_agent_iterations,
+    ai_tool_calls_total,
+)
 
 logger = structlog.get_logger()
 
@@ -38,12 +42,14 @@ class BuiltinAgentRuntime(BaseAgentRuntime):
         system_prompt: str = "You are a helpful data engineering assistant.",
         tools: ToolRegistry | None = None,
         max_iterations: int = 10,
+        name: str = "builtin",
         **kwargs: Any,
     ) -> None:
         self._llm = llm
         self._system_prompt = system_prompt
         self._tools = tools or tool_registry
         self._max_iterations = max_iterations
+        self._name = name
         self._history: list[dict[str, str]] = []
         register_builtin_tools()
 
@@ -64,6 +70,7 @@ class BuiltinAgentRuntime(BaseAgentRuntime):
             if step_result.get("done", False):
                 response = str(step_result.get("response", ""))
                 self._history.append({"role": "assistant", "content": response})
+                ai_agent_iterations.labels(agent=self._name).observe(iterations)
                 return {"response": response, "iterations": iterations, "tool_calls": tool_calls}
 
             # If tool was called, continue the loop
@@ -73,6 +80,7 @@ class BuiltinAgentRuntime(BaseAgentRuntime):
         # Hit max iterations
         final = "I've reached my reasoning limit. Here's what I have so far."
         self._history.append({"role": "assistant", "content": final})
+        ai_agent_iterations.labels(agent=self._name).observe(self._max_iterations)
         return {"response": final, "iterations": self._max_iterations, "tool_calls": tool_calls}
 
     async def step(self, message: str, **kwargs: Any) -> dict[str, Any]:
@@ -134,8 +142,10 @@ class BuiltinAgentRuntime(BaseAgentRuntime):
         try:
             result = self._tools.call(tool_name, **args)
             observation = f"Tool '{tool_name}' returned: {result}"
+            ai_tool_calls_total.labels(tool=tool_name, status="ok").inc()
         except Exception as e:
             observation = f"Tool '{tool_name}' failed: {e}"
+            ai_tool_calls_total.labels(tool=tool_name, status="error").inc()
 
         self._history.append(
             {"role": "assistant", "content": f"[tool: {tool_name}] {observation}"},

dataenginex-1.0.2/src/dataenginex/ai/observability/__init__.py

@@ -0,0 +1,19 @@
+"""Observability — audit logging, cost tracking, metrics, Langfuse tracing."""
+
+from __future__ import annotations
+
+from dataenginex.ai.observability.audit import AuditEntry, AuditLog
+from dataenginex.ai.observability.cost import CostTracker, TokenUsage
+from dataenginex.ai.observability.langfuse import LangfuseSink, get_sink, trace_generation
+from dataenginex.ai.observability.metrics import AgentMetrics
+
+__all__ = [
+    "AgentMetrics",
+    "AuditEntry",
+    "AuditLog",
+    "CostTracker",
+    "LangfuseSink",
+    "TokenUsage",
+    "get_sink",
+    "trace_generation",
+]

dataenginex-1.0.2/src/dataenginex/ai/observability/langfuse.py

@@ -0,0 +1,191 @@
+"""Langfuse tracing sink — ship LLM traces to self-hosted or cloud Langfuse.
+
+Records :class:`LLMResponse` calls as generation spans in Langfuse. Falls
+back to a no-op when the ``langfuse`` optional dependency is missing or the
+sink is disabled via env var.
+
+Configuration (env vars)::
+
+    DEX_LANGFUSE_ENABLED    — "true" to activate the sink (default "false")
+    LANGFUSE_PUBLIC_KEY     — project public key
+    LANGFUSE_SECRET_KEY     — project secret key
+    LANGFUSE_HOST           — endpoint (default https://cloud.langfuse.com)
+
+Install::
+
+    uv sync --group observability
+
+Example::
+
+    from dataenginex.ai.observability.langfuse import trace_generation
+
+    with trace_generation(name="summarise", model="gpt-4o") as ctx:
+        ctx["input"] = prompt
+        ctx["response"] = llm.generate(prompt)
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+import structlog
+
+from dataenginex.ml.llm import LLMResponse
+
+logger = structlog.get_logger()
+
+__all__ = ["LangfuseSink", "get_sink", "trace_generation"]
+
+
+class LangfuseSink:
+    """Thin wrapper over the Langfuse v4 SDK client.
+
+    All public methods are safe to call unconditionally — when langfuse is
+    not installed or the sink is disabled, they are no-ops.
+
+    Args:
+        public_key: Langfuse project public key; falls back to
+            ``LANGFUSE_PUBLIC_KEY`` env var.
+        secret_key: Langfuse project secret key; falls back to
+            ``LANGFUSE_SECRET_KEY`` env var.
+        host: Langfuse endpoint; falls back to ``LANGFUSE_HOST`` env var
+            (default ``https://cloud.langfuse.com``).
+        enabled: Override the ``DEX_LANGFUSE_ENABLED`` env var.
+    """
+
+    def __init__(
+        self,
+        public_key: str | None = None,
+        secret_key: str | None = None,
+        host: str | None = None,
+        enabled: bool | None = None,
+    ) -> None:
+        self._enabled = self._resolve_enabled(enabled)
+        self._client: Any = None
+        if not self._enabled:
+            return
+        try:
+            from langfuse import Langfuse
+        except ImportError:
+            logger.warning(
+                "langfuse not installed — tracing disabled; "
+                "install with: uv sync --group observability",
+            )
+            self._enabled = False
+            return
+        try:
+            self._client = Langfuse(
+                public_key=public_key or os.getenv("LANGFUSE_PUBLIC_KEY", ""),
+                secret_key=secret_key or os.getenv("LANGFUSE_SECRET_KEY", ""),
+                host=host or os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+            )
+            logger.info(
+                "langfuse sink initialised",
+                host=host or os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com"),
+            )
+        except Exception as exc:  # noqa: BLE001 — langfuse init surface varies
+            logger.warning("langfuse init failed", error=str(exc))
+            self._enabled = False
+
+    @staticmethod
+    def _resolve_enabled(explicit: bool | None) -> bool:
+        if explicit is not None:
+            return explicit
+        return os.getenv("DEX_LANGFUSE_ENABLED", "false").lower() == "true"
+
+    @property
+    def enabled(self) -> bool:
+        """Whether the sink will emit traces on call."""
+        return self._enabled and self._client is not None
+
+    def trace_generation(
+        self,
+        *,
+        name: str,
+        model: str,
+        input_messages: list[dict[str, str]] | str,
+        response: LLMResponse,
+        metadata: dict[str, Any] | None = None,
+        user_id: str | None = None,
+    ) -> None:
+        """Record a single generation event in Langfuse."""
+        if not self.enabled:
+            return
+        try:
+            with self._client.start_as_current_generation(
+                name=name,
+                model=model,
+                input=input_messages,
+            ) as gen:
+                gen.update(
+                    output=response.text,
+                    usage_details={
+                        "input": response.prompt_tokens,
+                        "output": response.completion_tokens,
+                        "total": response.total_tokens,
+                    },
+                    metadata=metadata or {},
+                )
+                if user_id:
+                    gen.update_trace(user_id=user_id)
+        except Exception:  # noqa: BLE001 — never let tracing break the request
+            logger.exception("langfuse trace failed", name=name)
+
+    def flush(self) -> None:
+        """Flush buffered traces (safe to call on shutdown)."""
+        if not self.enabled:
+            return
+        try:
+            self._client.flush()
+        except Exception:  # noqa: BLE001
+            logger.exception("langfuse flush failed")
+
+
+_GLOBAL_SINK: LangfuseSink | None = None
+
+
+def get_sink() -> LangfuseSink:
+    """Return the process-global :class:`LangfuseSink`, creating it lazily."""
+    global _GLOBAL_SINK  # noqa: PLW0603 — process-wide singleton
+    if _GLOBAL_SINK is None:
+        _GLOBAL_SINK = LangfuseSink()
+    return _GLOBAL_SINK
+
+
+@contextmanager
+def trace_generation(
+    name: str,
+    model: str,
+    **metadata: Any,
+) -> Iterator[dict[str, Any]]:
+    """Context manager that emits a Langfuse trace on exit.
+
+    The caller populates ``ctx["input"]`` and ``ctx["response"]`` inside the
+    block. When the block exits cleanly, the trace is shipped; exceptions
+    propagate unchanged.
+
+    Example::
+
+        with trace_generation("summarise", model="gpt-4o", agent="builtin") as ctx:
+            ctx["input"] = prompt
+            ctx["response"] = llm.generate(prompt)
+    """
+    ctx: dict[str, Any] = {"_start": time.monotonic(), "metadata": dict(metadata)}
+    try:
+        yield ctx
+    finally:
+        sink = get_sink()
+        response = ctx.get("response")
+        if sink.enabled and isinstance(response, LLMResponse):
+            sink.trace_generation(
+                name=name,
+                model=model,
+                input_messages=ctx.get("input", ""),
+                response=response,
+                metadata=ctx.get("metadata", {}),
+                user_id=ctx.get("user_id"),
+            )

{dataenginex-1.0.0 → dataenginex-1.0.2}/src/dataenginex/ai/retrieval/__init__.py

@@ -1,6 +1,7 @@
 """Retriever registry.
 
 Built-in retriever supports dense, sparse (BM25), and hybrid strategies.
+Graph retriever adds LightRAG-style dual-level (entity + semantic) retrieval.
 """
 
 from __future__ import annotations
@@ -9,3 +10,5 @@ from dataenginex.core.interfaces import BaseRetriever
 from dataenginex.core.registry import BackendRegistry
 
 retriever_registry: BackendRegistry[BaseRetriever] = BackendRegistry("retriever")
+
+__all__ = ["retriever_registry"]

dataenginex-1.0.2/src/dataenginex/ai/retrieval/graph.py

@@ -0,0 +1,159 @@
+"""Graph-augmented retriever — dual-level (entity + semantic) RAG.
+
+Inspired by LightRAG (EMNLP 2025). Retrieves at two complementary levels
+and fuses the rankings via reciprocal rank fusion (RRF):
+
+1. **Entity-level** (high-level, high recall) — pull docs mentioning the
+   named entities of the query.
+2. **Semantic-level** (low-level, high precision) — dense vector similarity
+   against the embedded query.
+
+Entity extraction defaults to a lightweight rule-based extractor
+(capitalised tokens and bigrams). Supply ``entity_extractor`` for LLM-driven
+NER or domain-specific extraction.
+
+Example::
+
+    from dataenginex.ai.retrieval.graph import GraphRetriever
+
+    retriever = GraphRetriever(
+        vector_store=store,
+        embed_fn=embed_fn,
+        documents=docs,
+    )
+    hits = retriever.retrieve("How does Snowflake handle schema drift?", top_k=5)
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Callable
+from typing import Any
+
+import structlog
+
+from dataenginex.ai.retrieval import retriever_registry
+from dataenginex.ai.retrieval.builtin import _BM25, _rrf
+from dataenginex.core.interfaces import BaseRetriever
+
+logger = structlog.get_logger()
+
+__all__ = ["GraphRetriever", "default_extract_entities"]
+
+
+_ENTITY_REGEX = re.compile(r"\b[A-Z][a-zA-Z0-9\-]+(?:\s+[A-Z][a-zA-Z0-9\-]+){0,3}\b")
+_STOPWORDS: frozenset[str] = frozenset(
+    {"The", "This", "That", "A", "An", "Is", "Are", "Was", "Were", "I", "We", "You", "It", "If"},
+)
+
+
+def default_extract_entities(text: str) -> list[str]:
+    """Rule-based entity extractor — capitalised tokens and multi-word phrases."""
+    return [m for m in _ENTITY_REGEX.findall(text) if m not in _STOPWORDS]
+
+
+@retriever_registry.decorator("graph")
+class GraphRetriever(BaseRetriever):
+    """Dual-level (entity + semantic) retriever.
+
+    Args:
+        vector_store: :class:`BaseVectorStore` for dense search. When ``None``
+            the semantic level falls back to BM25.
+        embed_fn: Callable mapping text → embedding vector.
+        entity_extractor: Entity extractor. Defaults to
+            :func:`default_extract_entities`.
+        documents: Initial documents to index (each dict must have ``"text"``).
+    """
+
+    def __init__(
+        self,
+        vector_store: Any = None,
+        embed_fn: Any = None,
+        entity_extractor: Callable[[str], list[str]] | None = None,
+        documents: list[dict[str, Any]] | None = None,
+        **_kwargs: Any,
+    ) -> None:
+        self._store = vector_store
+        self._embed_fn = embed_fn
+        self._extract = entity_extractor or default_extract_entities
+        self._docs: list[dict[str, Any]] = []
+        self._entity_index: dict[str, set[int]] = {}
+        self._bm25 = _BM25()
+        if documents:
+            self.index(documents)
+
+    def index(self, documents: list[dict[str, Any]]) -> None:
+        """Index documents for dual-level retrieval."""
+        self._docs = documents
+        self._entity_index = {}
+        for idx, doc in enumerate(documents):
+            for ent in self._extract(doc.get("text", "")):
+                self._entity_index.setdefault(ent.lower(), set()).add(idx)
+        self._bm25.index(documents)
+        if self._store is not None and self._embed_fn is not None:
+            for doc in documents:
+                embedding = self._embed_fn(doc.get("text", ""))
+                self._store.add(
+                    ids=[doc.get("id", str(id(doc)))],
+                    embeddings=[embedding],
+                    documents=[doc.get("text", "")],
+                    metadata=[doc.get("metadata", {})],
+                )
+        logger.info(
+            "graph retriever indexed",
+            docs=len(documents),
+            entities=len(self._entity_index),
+        )
+
+    def retrieve(
+        self,
+        query: str,
+        top_k: int = 10,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """Retrieve top_k docs by fusing entity-level and semantic-level rankings."""
+        pool = max(top_k * 2, top_k)
+        entity_ranks = self._entity_level(query, pool)
+        semantic_ranks = self._semantic_level(query, pool)
+        fused = _rrf(entity_ranks, semantic_ranks)[:top_k]
+        return [
+            {**self._docs[idx], "score": score, "method": "graph"}
+            for idx, score in fused
+            if 0 <= idx < len(self._docs)
+        ]
+
+    def _entity_level(self, query: str, top_k: int) -> list[tuple[int, float]]:
+        """High-level ranking: docs containing query entities, weighted by overlap."""
+        query_entities = [e.lower() for e in self._extract(query)]
+        if not query_entities:
+            return self._bm25.score(query, top_k)
+        counts: Counter[int] = Counter()
+        for ent in query_entities:
+            for doc_idx in self._entity_index.get(ent, ()):
+                counts[doc_idx] += 1
+        if not counts:
+            return self._bm25.score(query, top_k)
+        ranked = sorted(counts.items(), key=lambda x: x[1], reverse=True)[:top_k]
+        return [(idx, float(c)) for idx, c in ranked]
+
+    def _semantic_level(self, query: str, top_k: int) -> list[tuple[int, float]]:
+        """Low-level ranking: dense vector similarity (falls back to BM25)."""
+        if self._store is None or self._embed_fn is None:
+            return self._bm25.score(query, top_k)
+        embedding = self._embed_fn(query)
+        dense = self._store.search(embedding, top_k=top_k)
+        mapped: list[tuple[int, float]] = []
+        for r in dense:
+            doc_text = r.get("document", r.get("text", ""))
+            score = float(r.get("score", 0.0))
+            for i, doc in enumerate(self._docs):
+                if doc.get("text", "") == doc_text:
+                    mapped.append((i, score))
+                    break
+        return mapped
+
+    @property
+    def entities(self) -> dict[str, set[int]]:
+        """Expose the entity → doc-indices index (read-only view)."""
+        return self._entity_index

{dataenginex-1.0.0 → dataenginex-1.0.2}/src/dataenginex/api/__init__.py

@@ -20,7 +20,13 @@ Requires the ``[api]`` extra::
 from __future__ import annotations
 
 try:
-    from .auth import AuthMiddleware, AuthUser, create_token, decode_token
+    from .auth import (
+        AuthMiddleware,
+        AuthUser,
+        create_token,
+        decode_token,
+        decode_token_auto,
+    )
     from .errors import (
         APIHTTPException,
         BadRequestError,
@@ -30,6 +36,7 @@ try:
     from .health import ComponentHealth, HealthChecker, HealthStatus
     from .pagination import PaginatedResponse, PaginationMeta, paginate
     from .rate_limit import RateLimiter, RateLimitMiddleware
+    from .rbac import Role, has_role, require_role
 except ImportError as _exc:
     _MISSING_MSG = (
         "dataenginex.api requires the [api] extra. Install it with: pip install dataenginex[api]"
@@ -42,6 +49,7 @@ __all__ = [
     "AuthUser",
     "create_token",
     "decode_token",
+    "decode_token_auto",
     # Errors
     "APIHTTPException",
     "BadRequestError",
@@ -58,4 +66,8 @@ __all__ = [
     # Rate limiting
     "RateLimiter",
     "RateLimitMiddleware",
+    # RBAC
+    "Role",
+    "has_role",
+    "require_role",
 ]