artha-engine 0.1.1__py3-none-any.whl

artha_engine/__init__.py

@@ -0,0 +1,241 @@
+from artha_engine.decoders import (
+    BlobRefDecoder,
+    Bm25SearchDecoder,
+    Bm25SearchParams,
+    CollectionDecodeParams,
+    CollectionDecoder,
+    CosineSimilarityDecoder,
+    Decoder,
+    EmbeddingCandidate,
+    EmbeddingSearchHit,
+    EmbeddingSearchParams,
+    EmbeddingSearchResult,
+    FusedSearchHit,
+    GraphEdgeOutput,
+    JsonDecoder,
+    LLMArthaanuSummarizeDecoder,
+    LLMTextFormatDecoder,
+    LexicalMatchDecoder,
+    LexicalSearchHit,
+    LexicalSearchParams,
+    LexicalSearchResult,
+    NoDecoderParams,
+    QueryEmbeddingDecoder,
+    QueryEmbeddingParams,
+    ReciprocalRankFusionDecoder,
+    ReciprocalRankFusionParams,
+    RelationEdgeDecoder,
+    TextCandidate,
+    TextDecoder,
+)
+from artha_engine.encoders import (
+    BlobRefEncoder,
+    ChunkEmbeddingEncoder,
+    CollectionEncoder,
+    DeterministicEmbeddingEncoder,
+    Encoder,
+    GraphNodeEncoder,
+    JsonEncoder,
+    LLMJsonExtractEncoder,
+    RelationEncoder,
+    TextEncoder,
+)
+from artha_engine.lifecycle import (
+    CORE_LIFECYCLES_BY_NAME,
+    CollectionDedupeLifecycle,
+    JsonMergeLifecycle,
+    Lifecycle,
+    MultiLifecycle,
+    TextNormalizationLifecycle,
+)
+from artha_engine.representations import (
+    ARTHAANU_TYPES_BY_VALUE_TYPE,
+    Arthaanu,
+    BlobRefArthaanu,
+    CollectionArthaanu,
+    EmbeddingArthaanu,
+    GraphNodeArthaanu,
+    JsonArthaanu,
+    RelationArthaanu,
+    RelationValue,
+    SUPPORTED_VALUE_TYPES,
+    TextArthaanu,
+)
+from artha_engine.runtime import (
+    ArthaEngine,
+    AuthContext,
+    ComponentRegistry,
+    DEFAULT_DATABASE_URL,
+    DEFAULT_DB_PATH,
+    InMemoryArthaStore,
+    PostgresArthaStore,
+    SqliteArthaStore,
+    arthaanu_from_dict,
+    arthaanu_to_dict,
+    build_core_registry,
+    create_store,
+    default_store,
+    list_decoders,
+    list_encoders,
+    list_lifecycles,
+    list_projections,
+    normalize_auth_context,
+    normalize_profile_capabilities,
+    Projection,
+    ProfileCapability,
+    resolve_database_target,
+)
+from artha_engine.store import ArthaStore
+from artha_engine.llms import (
+    DEFAULT_LLM,
+    DEFAULT_LLM_MODEL,
+    DeterministicTextGenerator,
+    LiteLLMTextGenerator,
+    TemplateTextGenerator,
+    TextGenerator,
+    default_llm,
+)
+from artha_engine.retrieval import Bm25Index, reciprocal_rank_fusion
+from artha_engine.embeddings import (
+    DEFAULT_EMBEDDER,
+    DEFAULT_MODEL,
+    DeterministicTextEmbedder,
+    FastEmbedTextEmbedder,
+    NOMIC_DOCUMENT_PREFIX,
+    NOMIC_QUERY_PREFIX,
+    TextEmbedder,
+    default_embedder,
+)
+from artha_engine.app import (
+    ActionContext,
+    ActionDefinition,
+    ActionManifest,
+    ActionRegistry,
+    AnonymousAuthProvider,
+    ApiKeyAuthProvider,
+    ArthaApplication,
+    AuthProvider,
+    ClerkAuthProvider,
+    HttpExposure,
+    JwtAuthProvider,
+    McpHttpCompatibilityMiddleware,
+    ScopeAuthorizationPolicy,
+    action,
+    auth_provider_from_env,
+    streamable_http_app,
+)
+
+__all__ = [
+    "ARTHAANU_TYPES_BY_VALUE_TYPE",
+    "Arthaanu",
+    "BlobRefArthaanu",
+    "CollectionArthaanu",
+    "TextArthaanu",
+    "EmbeddingArthaanu",
+    "JsonArthaanu",
+    "RelationArthaanu",
+    "RelationValue",
+    "SUPPORTED_VALUE_TYPES",
+    "GraphNodeArthaanu",
+    "BlobRefEncoder",
+    "ChunkEmbeddingEncoder",
+    "CollectionEncoder",
+    "DeterministicEmbeddingEncoder",
+    "Encoder",
+    "GraphNodeEncoder",
+    "JsonEncoder",
+    "LLMJsonExtractEncoder",
+    "RelationEncoder",
+    "TextEncoder",
+    "CORE_LIFECYCLES_BY_NAME",
+    "CollectionDedupeLifecycle",
+    "JsonMergeLifecycle",
+    "Lifecycle",
+    "MultiLifecycle",
+    "TextNormalizationLifecycle",
+    "Bm25Index",
+    "BlobRefDecoder",
+    "Bm25SearchDecoder",
+    "Bm25SearchParams",
+    "CollectionDecodeParams",
+    "CollectionDecoder",
+    "CosineSimilarityDecoder",
+    "Decoder",
+    "DEFAULT_LLM",
+    "DEFAULT_LLM_MODEL",
+    "DeterministicTextGenerator",
+    "EmbeddingCandidate",
+    "EmbeddingSearchHit",
+    "EmbeddingSearchParams",
+    "EmbeddingSearchResult",
+    "FusedSearchHit",
+    "GraphEdgeOutput",
+    "JsonDecoder",
+    "LLMArthaanuSummarizeDecoder",
+    "LLMJsonExtractEncoder",
+    "LLMTextFormatDecoder",
+    "LexicalMatchDecoder",
+    "LexicalSearchHit",
+    "LexicalSearchParams",
+    "LexicalSearchResult",
+    "LiteLLMTextGenerator",
+    "NoDecoderParams",
+    "QueryEmbeddingDecoder",
+    "QueryEmbeddingParams",
+    "ReciprocalRankFusionDecoder",
+    "ReciprocalRankFusionParams",
+    "RelationEdgeDecoder",
+    "TemplateTextGenerator",
+    "TextCandidate",
+    "TextDecoder",
+    "TextGenerator",
+    "default_llm",
+    "reciprocal_rank_fusion",
+    "ArthaEngine",
+    "ArthaStore",
+    "AuthContext",
+    "ComponentRegistry",
+    "DEFAULT_DATABASE_URL",
+    "DEFAULT_DB_PATH",
+    "InMemoryArthaStore",
+    "PostgresArthaStore",
+    "Projection",
+    "ProfileCapability",
+    "SqliteArthaStore",
+    "arthaanu_from_dict",
+    "arthaanu_to_dict",
+    "build_core_registry",
+    "create_store",
+    "default_store",
+    "resolve_database_target",
+    "list_decoders",
+    "list_encoders",
+    "list_lifecycles",
+    "list_projections",
+    "normalize_auth_context",
+    "normalize_profile_capabilities",
+    "DEFAULT_EMBEDDER",
+    "DEFAULT_MODEL",
+    "DeterministicTextEmbedder",
+    "FastEmbedTextEmbedder",
+    "NOMIC_DOCUMENT_PREFIX",
+    "NOMIC_QUERY_PREFIX",
+    "TextEmbedder",
+    "default_embedder",
+    "ActionContext",
+    "ActionDefinition",
+    "ActionManifest",
+    "ActionRegistry",
+    "AnonymousAuthProvider",
+    "ApiKeyAuthProvider",
+    "ArthaApplication",
+    "AuthProvider",
+    "ClerkAuthProvider",
+    "HttpExposure",
+    "JwtAuthProvider",
+    "McpHttpCompatibilityMiddleware",
+    "ScopeAuthorizationPolicy",
+    "action",
+    "auth_provider_from_env",
+    "streamable_http_app",
+]

artha_engine/app/__init__.py

@@ -0,0 +1,71 @@
+from artha_engine.app.actions import (
+    ActionDefinition,
+    ActionKind,
+    ActionManifest,
+    ActionRegistry,
+    CliExposure,
+    HttpExposure,
+    McpExposure,
+    action,
+)
+from artha_engine.app.application import ArthaApplication
+from artha_engine.app.auth import (
+    AnonymousAuthProvider,
+    ApiKeyAuthProvider,
+    AuthenticationError,
+    AuthConfigurationError,
+    AuthProvider,
+    ClerkAuthProvider,
+    JwtAuthProvider,
+    auth_provider_from_env,
+)
+from artha_engine.app.managed_api_keys import (
+    CompositeAuthProvider,
+    ManagedApiKeyAuthProvider,
+    enable_managed_api_keys,
+    register_api_key_actions,
+)
+from artha_engine.app.authorization import (
+    AuthorizationDenied,
+    AuthorizationPolicy,
+    ScopeAuthorizationPolicy,
+)
+from artha_engine.app.context import ActionContext
+from artha_engine.app.mcp import (
+    McpHttpCompatibilityMiddleware,
+    create_mcp_server,
+    run_mcp,
+    streamable_http_app,
+)
+
+__all__ = [
+    "ActionContext",
+    "ActionDefinition",
+    "ActionKind",
+    "ActionManifest",
+    "ActionRegistry",
+    "AnonymousAuthProvider",
+    "ApiKeyAuthProvider",
+    "ArthaApplication",
+    "AuthenticationError",
+    "AuthConfigurationError",
+    "AuthProvider",
+    "AuthorizationDenied",
+    "AuthorizationPolicy",
+    "CliExposure",
+    "CompositeAuthProvider",
+    "ClerkAuthProvider",
+    "HttpExposure",
+    "JwtAuthProvider",
+    "ManagedApiKeyAuthProvider",
+    "McpExposure",
+    "McpHttpCompatibilityMiddleware",
+    "ScopeAuthorizationPolicy",
+    "action",
+    "auth_provider_from_env",
+    "create_mcp_server",
+    "enable_managed_api_keys",
+    "register_api_key_actions",
+    "run_mcp",
+    "streamable_http_app",
+]

artha_engine/app/actions.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import inspect
+import re
+import asyncio
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from types import ModuleType, UnionType
+from typing import Any, Literal, get_args, get_origin, get_type_hints
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, create_model
+
+from artha_engine.app.context import ActionContext
+from artha_engine.runtime.auth import AuthContext
+from artha_engine.runtime.engine import ArthaEngine
+
+ActionKind = Literal["read", "write", "destructive"]
+_ACTION_ATTRIBUTE = "__artha_action_spec__"
+_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_.-]*$")
+
+
+@dataclass(frozen=True)
+class HttpExposure:
+    method: str
+    path: str
+    status_code: int = 200
+
+    def __post_init__(self) -> None:
+        method = self.method.upper()
+        if method not in {"GET", "POST", "PUT", "PATCH", "DELETE"}:
+            raise ValueError(f"Unsupported action HTTP method: {self.method}")
+        if not self.path.startswith("/"):
+            raise ValueError("Action HTTP paths must begin with /")
+        object.__setattr__(self, "method", method)
+
+
+@dataclass(frozen=True)
+class McpExposure:
+    name: str
+
+
+@dataclass(frozen=True)
+class CliExposure:
+    command: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    name: str
+    description: str | None = None
+    version: str = "1"
+    kind: ActionKind = "read"
+    scopes: tuple[str, ...] = ()
+    public: bool = False
+    http: HttpExposure | None = None
+    mcp: McpExposure | None = None
+    cli: CliExposure | None = None
+    inject: dict[str, str] = field(default_factory=dict)
+    tags: tuple[str, ...] = ()
+
+
+class ActionManifest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    description: str
+    version: str
+    kind: ActionKind
+    scopes: list[str] = Field(default_factory=list)
+    public: bool
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any]
+    http: dict[str, Any] | None = None
+    mcp: dict[str, Any] | None = None
+    cli: dict[str, Any] | None = None
+    tags: list[str] = Field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ActionDefinition:
+    spec: ActionSpec
+    function: Callable[..., Any]
+    input_model: type[BaseModel]
+    return_annotation: Any
+    public_parameters: tuple[str, ...]
+    model_parameter: str | None
+    injected_parameters: dict[str, str]
+
+    @property
+    def name(self) -> str:
+        return self.spec.name
+
+    @property
+    def description(self) -> str:
+        return self.spec.description or inspect.getdoc(self.function) or self.name
+
+    @property
+    def kind(self) -> ActionKind:
+        return self.spec.kind
+
+    @property
+    def scopes(self) -> tuple[str, ...]:
+        return self.spec.scopes
+
+    @property
+    def public(self) -> bool:
+        return self.spec.public
+
+    @property
+    def http(self) -> HttpExposure | None:
+        return self.spec.http
+
+    @property
+    def mcp(self) -> McpExposure | None:
+        return self.spec.mcp
+
+    @property
+    def cli(self) -> CliExposure | None:
+        return self.spec.cli
+
+    def manifest(self) -> ActionManifest:
+        output_schema: dict[str, Any] = {}
+        if self.return_annotation not in {Any, inspect.Signature.empty, None}:
+            output_schema = TypeAdapter(self.return_annotation).json_schema()
+        return ActionManifest(
+            name=self.name,
+            description=self.description,
+            version=self.spec.version,
+            kind=self.kind,
+            scopes=list(self.scopes),
+            public=self.public,
+            input_schema=self.input_model.model_json_schema(),
+            output_schema=output_schema,
+            http=(
+                {
+                    "method": self.http.method,
+                    "path": self.http.path,
+                    "status_code": self.http.status_code,
+                }
+                if self.http
+                else None
+            ),
+            mcp={"name": self.mcp.name} if self.mcp else None,
+            cli={"command": list(self.cli.command)} if self.cli else None,
+            tags=list(self.spec.tags),
+        )
+
+    def build_arguments(
+        self,
+        payload: BaseModel | dict[str, Any] | None,
+        context: ActionContext,
+    ) -> dict[str, Any]:
+        validated = (
+            payload
+            if isinstance(payload, self.input_model)
+            else self.input_model.model_validate(payload or {})
+        )
+        arguments: dict[str, Any] = {}
+        if self.model_parameter is not None:
+            arguments[self.model_parameter] = validated
+        else:
+            for name in self.public_parameters:
+                arguments[name] = getattr(validated, name)
+
+        hints = get_type_hints(self.function)
+        for name, parameter in inspect.signature(self.function).parameters.items():
+            annotation = hints.get(name, parameter.annotation)
+            if annotation is ArthaEngine:
+                arguments[name] = context.engine
+            elif annotation is ActionContext:
+                arguments[name] = context
+            elif annotation is AuthContext:
+                arguments[name] = context.auth
+            elif name in self.injected_parameters:
+                arguments[name] = context.require_service(self.injected_parameters[name])
+        return arguments
+
+    async def invoke(
+        self,
+        payload: BaseModel | dict[str, Any] | None,
+        context: ActionContext,
+    ) -> Any:
+        arguments = self.build_arguments(payload, context)
+        if inspect.iscoroutinefunction(self.function):
+            result = self.function(**arguments)
+        else:
+            result = await asyncio.to_thread(self.function, **arguments)
+        if inspect.isawaitable(result):
+            result = await result
+        if self.return_annotation not in {Any, inspect.Signature.empty, None}:
+            result = TypeAdapter(self.return_annotation).validate_python(result)
+        return result
+
+
+class ActionRegistry:
+    """Typed application functions exposed through HTTP, MCP, and CLI."""
+
+    def __init__(self) -> None:
+        self._actions: dict[str, ActionDefinition] = {}
+
+    def action(self, **kwargs: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        def decorator(function: Callable[..., Any]) -> Callable[..., Any]:
+            decorated = action(**kwargs)(function)
+            self.register(decorated)
+            return decorated
+
+        return decorator
+
+    def register(self, function: Callable[..., Any]) -> ActionDefinition:
+        spec = getattr(function, _ACTION_ATTRIBUTE, None)
+        if not isinstance(spec, ActionSpec):
+            raise ValueError(f"Function is not decorated with @action: {function.__name__}")
+        if spec.name in self._actions:
+            raise ValueError(f"Action is already registered: {spec.name}")
+        definition = _build_definition(function, spec)
+        self._actions[spec.name] = definition
+        return definition
+
+    def discover(self, module: ModuleType) -> list[ActionDefinition]:
+        discovered: list[ActionDefinition] = []
+        for value in vars(module).values():
+            if callable(value) and isinstance(getattr(value, _ACTION_ATTRIBUTE, None), ActionSpec):
+                if getattr(value, _ACTION_ATTRIBUTE).name not in self._actions:
+                    discovered.append(self.register(value))
+        return discovered
+
+    def get(self, name: str) -> ActionDefinition:
+        try:
+            return self._actions[name]
+        except KeyError as exc:
+            raise KeyError(f"Unknown action: {name}") from exc
+
+    def list(self) -> list[ActionDefinition]:
+        return [self._actions[name] for name in sorted(self._actions)]
+
+    def manifests(self) -> list[dict[str, Any]]:
+        return [item.manifest().model_dump(mode="json") for item in self.list()]
+
+
+def action(
+    *,
+    name: str,
+    description: str | None = None,
+    version: str = "1",
+    kind: ActionKind = "read",
+    scopes: Iterable[str] = (),
+    public: bool = False,
+    http: bool | str | tuple[str, str] | HttpExposure = True,
+    mcp: bool | str | McpExposure = True,
+    cli: bool | str | Iterable[str] | CliExposure = True,
+    inject: Iterable[str] | dict[str, str] = (),
+    tags: Iterable[str] = (),
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Mark a typed function as an Artha application action."""
+
+    if not _NAME_PATTERN.fullmatch(name):
+        raise ValueError(
+            "Action names must start with a lowercase letter and use lowercase "
+            "letters, numbers, dots, dashes, or underscores"
+        )
+    if kind not in {"read", "write", "destructive"}:
+        raise ValueError(f"Unsupported action kind: {kind}")
+    spec = ActionSpec(
+        name=name,
+        description=description,
+        version=version,
+        kind=kind,
+        scopes=tuple(scopes),
+        public=public,
+        http=_normalize_http(name, http),
+        mcp=_normalize_mcp(name, mcp),
+        cli=_normalize_cli(name, cli),
+        inject=_normalize_injections(inject),
+        tags=tuple(tags),
+    )
+
+    def decorator(function: Callable[..., Any]) -> Callable[..., Any]:
+        if hasattr(function, _ACTION_ATTRIBUTE):
+            raise ValueError(f"Function already has an Artha action: {function.__name__}")
+        setattr(function, _ACTION_ATTRIBUTE, spec)
+        return function
+
+    return decorator
+
+
+def _build_definition(function: Callable[..., Any], spec: ActionSpec) -> ActionDefinition:
+    signature = inspect.signature(function)
+    hints = get_type_hints(function)
+    public: list[tuple[str, inspect.Parameter, Any]] = []
+    injected: dict[str, str] = dict(spec.inject)
+
+    for name, parameter in signature.parameters.items():
+        annotation = hints.get(name, parameter.annotation)
+        if annotation in {ArthaEngine, ActionContext, AuthContext}:
+            continue
+        if name in injected:
+            continue
+        if annotation is inspect.Signature.empty:
+            raise TypeError(f"Action parameter {spec.name}.{name} must have a type annotation")
+        public.append((name, parameter, annotation))
+
+    model_parameter: str | None = None
+    if len(public) == 1 and _is_model_type(public[0][2]):
+        model_parameter = public[0][0]
+        input_model = public[0][2]
+        public_names: tuple[str, ...] = ()
+    else:
+        fields: dict[str, tuple[Any, Any]] = {}
+        for name, parameter, annotation in public:
+            default: Any = ...
+            if parameter.default is not inspect.Signature.empty:
+                default = parameter.default
+            fields[name] = (annotation, default)
+        model_name = "".join(part.title() for part in re.split(r"[_.-]", spec.name)) + "Input"
+        input_model = create_model(model_name, **fields)
+        public_names = tuple(name for name, _, _ in public)
+
+    return ActionDefinition(
+        spec=spec,
+        function=function,
+        input_model=input_model,
+        return_annotation=hints.get("return", signature.return_annotation),
+        public_parameters=public_names,
+        model_parameter=model_parameter,
+        injected_parameters=injected,
+    )
+
+
+def _normalize_http(
+    name: str,
+    value: bool | str | tuple[str, str] | HttpExposure,
+) -> HttpExposure | None:
+    if value is False:
+        return None
+    if isinstance(value, HttpExposure):
+        return value
+    if value is True:
+        return HttpExposure("POST", f"/actions/{name.replace('.', '/')}")
+    if isinstance(value, tuple):
+        return HttpExposure(value[0], value[1])
+    method, separator, path = value.partition(" ")
+    if not separator:
+        return HttpExposure("POST", value)
+    return HttpExposure(method, path)
+
+
+def _normalize_mcp(name: str, value: bool | str | McpExposure) -> McpExposure | None:
+    if value is False:
+        return None
+    if isinstance(value, McpExposure):
+        return value
+    if isinstance(value, str):
+        return McpExposure(value)
+    return McpExposure(re.sub(r"[^a-zA-Z0-9_]", "_", name))
+
+
+def _normalize_cli(
+    name: str,
+    value: bool | str | Iterable[str] | CliExposure,
+) -> CliExposure | None:
+    if value is False:
+        return None
+    if isinstance(value, CliExposure):
+        return value
+    if value is True:
+        return CliExposure(tuple(part for part in re.split(r"[.\s]+", name) if part))
+    if isinstance(value, str):
+        return CliExposure(tuple(part for part in value.split() if part))
+    return CliExposure(tuple(value))
+
+
+def _normalize_injections(value: Iterable[str] | dict[str, str]) -> dict[str, str]:
+    if isinstance(value, dict):
+        return dict(value)
+    return {name: name for name in value}
+
+
+def _is_model_type(annotation: Any) -> bool:
+    return inspect.isclass(annotation) and issubclass(annotation, BaseModel)
+
+
+def unwrap_optional(annotation: Any) -> tuple[Any, bool]:
+    origin = get_origin(annotation)
+    if origin not in {UnionType, getattr(__import__("typing"), "Union")}:
+        return annotation, False
+    args = get_args(annotation)
+    without_none = tuple(arg for arg in args if arg is not type(None))
+    if len(without_none) == 1 and len(without_none) != len(args):
+        return without_none[0], True
+    return annotation, False