fervis 0.1.0__py3-none-any.whl

fervis/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fervis.project import (
+    DatabaseUrlPersistence,
+    DjangoAppSource,
+    DjangoDatabasePersistence,
+    DjangoIntegration,
+    FastAPIAppSource,
+    FastAPIIntegration,
+    FervisConfig,
+    FlaskAppSource,
+    FlaskIntegration,
+    HostConfig,
+    ModelConfig,
+    PersistenceTarget,
+    ProviderConfig,
+    RuntimeRoutes,
+    SQLitePersistence,
+    discover_project,
+)
+from fervis.project.configuration import ConfigProblem, load_fervis_project_config
+
+
+def configured_fervis(*, root: Path | str | None = None):
+    project = discover_project(Path(root) if root is not None else Path.cwd())
+    loaded = load_fervis_project_config(project)
+    if isinstance(loaded, ConfigProblem):
+        raise RuntimeError(loaded.message)
+    return loaded.integration
+
+
+__all__ = [
+    "DatabaseUrlPersistence",
+    "DjangoAppSource",
+    "DjangoDatabasePersistence",
+    "DjangoIntegration",
+    "FastAPIAppSource",
+    "FastAPIIntegration",
+    "FervisConfig",
+    "FlaskAppSource",
+    "FlaskIntegration",
+    "HostConfig",
+    "ModelConfig",
+    "PersistenceTarget",
+    "ProviderConfig",
+    "RuntimeRoutes",
+    "SQLitePersistence",
+    "configured_fervis",
+]

fervis/django/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from fervis import configured_fervis
+from fervis.project import DjangoIntegration
+
+__all__ = ["DjangoIntegration", "configured_fervis"]

fervis/django/urls.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from fervis.interfaces.django.urls import urlpatterns
+
+__all__ = ["urlpatterns"]

fervis/error_codes.py

@@ -0,0 +1,24 @@
+"""Fervis error codes used by framework and provider adapters."""
+
+VALIDATION_ERROR = "validation_error"
+MISSING_REQUIRED_PARAMETER = "missing_required_parameter"
+INVALID_MODEL_KEY = "invalid_model_key"
+
+INSUFFICIENT_PERMISSIONS = "insufficient_permissions"
+READ_CONTEXT_REQUIRED = "read_context_required"
+
+RATE_LIMIT_EXCEEDED = "rate_limit_exceeded"
+
+INTERNAL_ERROR = "internal_error"
+CONFIGURATION_ERROR = "configuration_error"
+LLM_API_ERROR = "llm_api_error"
+LLM_API_CONNECTION_ERROR = "llm_api_connection_error"
+LLM_API_TIMEOUT = "llm_api_timeout"
+LLM_API_BAD_REQUEST = "llm_api_bad_request"
+LLM_API_AUTHENTICATION_ERROR = "llm_api_authentication_error"
+LLM_API_PERMISSION_ERROR = "llm_api_permission_error"
+LLM_API_NOT_FOUND = "llm_api_not_found"
+LLM_API_CONFLICT = "llm_api_conflict"
+LLM_API_RATE_LIMITED = "llm_api_rate_limited"
+LLM_API_INTERNAL_ERROR = "llm_api_internal_error"
+LLM_API_RESPONSE_INVALID = "llm_api_response_invalid"

fervis/errors.py

@@ -0,0 +1,388 @@
+"""Fervis-owned API error hierarchy.
+
+This module intentionally has no Django/FastAPI/Flask dependency. Framework
+adapters may translate these errors into host responses, but provider and core
+runtime code should not import host application error modules.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import error_codes as codes
+
+
+class APIError(Exception):
+    """Base exception for structured Fervis errors."""
+
+    error_type = "system"
+    status_code: int | None = None
+    retryable = False
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        developer_message: str | None = None,
+        context: dict[str, Any] | None = None,
+        details: list[dict[str, Any]] | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.developer_message = developer_message or message
+        self.context = dict(context or {})
+        self.details = list(details or [])
+        self.retry_after = retry_after
+        super().__init__(message)
+
+    @classmethod
+    def configuration_error(
+        cls, message: str = "Service configuration is invalid."
+    ) -> "APIError":
+        return build_error(cls, codes.CONFIGURATION_ERROR, message)
+
+    @classmethod
+    def internal_error(cls) -> "APIError":
+        return build_error(cls, codes.INTERNAL_ERROR, "An unexpected error occurred.")
+
+
+class Validation(APIError):
+    error_type = "validation"
+    status_code = 400
+
+    @classmethod
+    def request_validation_failed(
+        cls,
+        *,
+        message: str = "Request validation failed.",
+        details: list[dict[str, Any]] | None = None,
+    ) -> "Validation":
+        return build_error(
+            cls,
+            codes.VALIDATION_ERROR,
+            message,
+            details=details or [],
+        )
+
+    @classmethod
+    def invalid_model_key(
+        cls, *, allowed_models: list[str], message: str = "Invalid model key."
+    ) -> "Validation":
+        return build_error(
+            cls,
+            codes.INVALID_MODEL_KEY,
+            message,
+            context={"allowed_models": list(allowed_models)},
+        )
+
+
+class Authorization(APIError):
+    error_type = "authorization"
+    status_code = 403
+
+    @classmethod
+    def insufficient_permissions(cls) -> "Authorization":
+        return build_error(
+            cls,
+            codes.INSUFFICIENT_PERMISSIONS,
+            "You do not have permission to perform this action.",
+        )
+
+
+class Authentication(APIError):
+    error_type = "authorization"
+    status_code = 401
+
+    @classmethod
+    def read_context_required(
+        cls,
+        message: str = "Fervis could not capture an authenticated read context.",
+    ) -> "Authentication":
+        return build_error(cls, codes.READ_CONTEXT_REQUIRED, message)
+
+
+class NotFound(APIError):
+    error_type = "not_found"
+    status_code = 404
+
+    @classmethod
+    def for_resource(
+        cls,
+        resource_type: str,
+        resource_id: str | int | None = "unknown",
+        *,
+        message: str | None = None,
+    ) -> "NotFound":
+        return build_error(
+            cls,
+            f"{resource_type}_not_found",
+            message or f"{resource_type.replace('_', ' ').title()} not found.",
+            developer_message=f"{resource_type} {resource_id} does not exist",
+            context={"resource_type": resource_type, "resource_id": str(resource_id)},
+        )
+
+
+class RateLimit(APIError):
+    error_type = "rate_limit"
+    status_code = 429
+    retryable = True
+
+    @classmethod
+    def llm_api_rate_limited(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+        retry_after: int | None = None,
+    ) -> "RateLimit":
+        return build_error(
+            cls,
+            codes.LLM_API_RATE_LIMITED,
+            "LLM provider rate limit exceeded.",
+            context=_provider_context(provider, reason, error_class, context),
+            retry_after=retry_after,
+        )
+
+
+class Unavailable(APIError):
+    error_type = "system"
+    status_code = 502
+    retryable = True
+
+    @classmethod
+    def llm_api_error(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_ERROR,
+            message="LLM provider is currently unavailable.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_connection_error(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_CONNECTION_ERROR,
+            message="Could not connect to the LLM provider.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_timeout(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_TIMEOUT,
+            message="LLM provider timed out.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_bad_request(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_BAD_REQUEST,
+            message="LLM request was rejected by the provider.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_authentication_error(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_AUTHENTICATION_ERROR,
+            message="LLM provider authentication failed.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_permission_error(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_PERMISSION_ERROR,
+            message="LLM provider denied access to the requested resource.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_not_found(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_NOT_FOUND,
+            message="LLM provider resource was not found.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_conflict(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_CONFLICT,
+            message="LLM provider reported a request conflict.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_internal_error(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_INTERNAL_ERROR,
+            message="LLM provider encountered an internal error.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def llm_api_response_invalid(
+        cls,
+        *,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return cls._llm_error(
+            code=codes.LLM_API_RESPONSE_INVALID,
+            message="LLM provider returned an invalid response payload.",
+            provider=provider,
+            reason=reason,
+            error_class=error_class,
+            context=context,
+        )
+
+    @classmethod
+    def _llm_error(
+        cls,
+        *,
+        code: str,
+        message: str,
+        provider: str,
+        reason: str | None = None,
+        error_class: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> "Unavailable":
+        return build_error(
+            cls,
+            code,
+            message,
+            context=_provider_context(provider, reason, error_class, context),
+        )
+
+
+def build_error(
+    exception_cls: type[APIError],
+    code: str,
+    message: str,
+    *,
+    context: dict[str, Any] | None = None,
+    developer_message: str | None = None,
+    details: list[dict[str, Any]] | None = None,
+    retry_after: int | None = None,
+) -> APIError:
+    return exception_cls(
+        code=code,
+        message=message,
+        developer_message=developer_message,
+        context=context,
+        details=details,
+        retry_after=retry_after,
+    )
+
+
+def _provider_context(
+    provider: str,
+    reason: str | None,
+    error_class: str | None,
+    context: dict[str, Any] | None,
+) -> dict[str, Any]:
+    payload = {
+        "provider": provider,
+        "reason": reason,
+        "error_class": error_class,
+    }
+    if context:
+        payload.update(context)
+    return payload

fervis/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Evaluation tooling for portable Fervis runtime checks."""

fervis/fastapi/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from fervis import configured_fervis
+from fervis.interfaces.fastapi import fervis_fastapi_router
+from fervis.project import FastAPIIntegration
+
+__all__ = [
+    "FastAPIIntegration",
+    "configured_fervis",
+    "fervis_fastapi_router",
+]

fervis/flask/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from fervis import configured_fervis
+from fervis.interfaces.flask import fervis_flask_blueprint
+from fervis.project import FlaskIntegration
+
+__all__ = [
+    "FlaskIntegration",
+    "configured_fervis",
+    "fervis_flask_blueprint",
+]

fervis/host_api/adapters/django/__init__.py

@@ -0,0 +1 @@
+"""Django + DRF host API adapter package."""

fervis/host_api/adapters/django/adapter.py

@@ -0,0 +1,99 @@
+"""Django framework adapter for Fervis endpoint access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fervis.host_api.contracts import EndpointContract
+from fervis.host_api.adapters.http import (
+    execute_http_read,
+    http_read_config_from_auth_schema,
+)
+from fervis.host_api.contracts.authority import ReadAuthority, ReadContextRef
+from fervis.host_api.contracts.credentials import DelegatedReadCredential
+from fervis.host_api.contracts.read import ReadInvocation
+from fervis.host_api.credentials import (
+    credential_overlay_from_auth_schema,
+    delegated_credential_from_request,
+)
+from fervis.host_api.contracts.ports import (
+    EndpointExecutionError,
+    EndpointExecutionResult,
+)
+from fervis.lookup.relation_catalog.from_host_api import (
+    relation_catalog_from_endpoint_contracts,
+)
+from fervis.lookup.relation_catalog import RelationCatalog
+from fervis.project.source_scope import DjangoSourceScope
+
+from .catalog import get_endpoint_contracts
+from .catalog import get_endpoint_contract
+from .principal import capture_django_read_context, resolve_django_read_context_ref
+from .executor import execute_get_endpoint
+
+
+class DjangoHostApiAdapter:
+    def __init__(
+        self,
+        *,
+        sources: tuple[DjangoSourceScope, ...],
+        auth_schema: dict[str, object] | None = None,
+    ):
+        self.sources = tuple(sources)
+        self.auth_schema = auth_schema
+
+    def describe_sources(self) -> tuple[EndpointContract, ...]:
+        return get_endpoint_contracts(sources=self.sources)
+
+    def build_relation_catalog(self) -> RelationCatalog:
+        return relation_catalog_from_endpoint_contracts(self.describe_sources())
+
+    def capture_read_context(self, request: Any) -> ReadContextRef:
+        return capture_django_read_context(request)
+
+    def capture_delegated_credential(
+        self,
+        request: Any,
+    ) -> DelegatedReadCredential | None:
+        return delegated_credential_from_request(
+            schema=self.auth_schema,
+            request=request,
+        )
+
+    def execute_read(
+        self,
+        *,
+        authority: ReadAuthority,
+        invocation: ReadInvocation,
+    ) -> EndpointExecutionResult:
+        http_config = http_read_config_from_auth_schema(self.auth_schema)
+        if http_config is not None:
+            contract = get_endpoint_contract(
+                invocation.endpoint_name,
+                sources=self.sources,
+            )
+            if contract is None:
+                raise EndpointExecutionError(
+                    f"Unknown endpoint: {invocation.endpoint_name}"
+                )
+            return execute_http_read(
+                contract=contract,
+                authority=authority,
+                invocation=invocation,
+                config=http_config,
+            )
+        user = resolve_django_read_context_ref(authority.read_context_ref)
+        return execute_get_endpoint(
+            endpoint_name=invocation.endpoint_name,
+            user=user,
+            sources=self.sources,
+            path_params=dict(invocation.path_params),
+            query_params=dict(invocation.query_params),
+            page_policy=(
+                None if invocation.page_policy is None else dict(invocation.page_policy)
+            ),
+            transport_overlay=credential_overlay_from_auth_schema(
+                schema=self.auth_schema,
+                credential=authority.delegated_credential,
+            ),
+        )