artha-engine 0.1.1__tar.gz

artha_engine-0.1.1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.3
+Name: artha-engine
+Version: 0.1.1
+Summary: Semantic memory engine with append-only event ledger, Arthaanu representations, and projection replay.
+Keywords: memory,rag,semantic-events,projections,agents
+Author: Alphanimble
+Author-email: Alphanimble <rakshith.g@alphanimble.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: fastembed>=0.6.0
+Requires-Dist: litellm>=1.60.0
+Requires-Dist: psycopg[binary]>=3.2.0
+Requires-Dist: fastapi>=0.115.0 ; extra == 'app'
+Requires-Dist: uvicorn[standard]>=0.34.0 ; extra == 'app'
+Requires-Dist: httpx>=0.28.0 ; extra == 'app'
+Requires-Dist: pyjwt[crypto]>=2.10.0,<3 ; extra == 'auth'
+Requires-Dist: mcp>=1.0.0,<2 ; extra == 'mcp'
+Requires-Dist: fastapi>=0.115.0 ; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.34.0 ; extra == 'server'
+Requires-Dist: fastapi>=0.115.0 ; extra == 'workbench'
+Requires-Dist: uvicorn[standard]>=0.34.0 ; extra == 'workbench'
+Requires-Python: >=3.12
+Provides-Extra: app
+Provides-Extra: auth
+Provides-Extra: mcp
+Provides-Extra: server
+Provides-Extra: workbench
+Description-Content-Type: text/markdown
+
+# Artha Engine
+
+Artha Engine is the core Python library for building Arthaanu-based memory
+systems. It provides:
+
+- typed Arthaanu representations
+- encoder, lifecycle, decoder, and projection registries
+- an append-only semantic event ledger
+- SQLite and in-memory stores
+- projection replay with watermarks and status
+- typed product actions exposed as HTTP, MCP, and CLI tools
+- Clerk/JWT/API-key authentication adapters
+- portable OCI application builds
+- a small `artha` CLI for inspection and local operation
+
+The engine is intentionally small. Product-specific memory types, profiles,
+retrieval policy, and domain projections should usually live in userland
+packages built on top of the engine.
+
+## Install Locally
+
+From this repository:
+
+```bash
+cd artha_engine
+uv sync
+uv run artha doctor
+```
+
+To run the FastAPI runtime:
+
+```bash
+uv sync --extra server
+uv run artha serve --port 8765
+```
+
+Create product actions with one typed declaration:
+
+```python
+@actions.action(
+    name="memory.search",
+    http=("POST", "/memories/search"),
+    mcp=True,
+    cli="memory search",
+    scopes=["memory:read"],
+)
+def search(input: SearchInput, context: ActionContext) -> SearchOutput:
+    ...
+```
+
+## CLI
+
+```bash
+artha doctor
+artha registry
+artha encode text --input "Artha keeps semantic events canonical."
+artha events --limit 5
+artha objects --limit 5
+artha projections
+artha check
+artha build
+```
+
+Use `--db path/to/artha.db` to point commands at a specific SQLite ledger.
+Most commands support `--json` for agent-friendly output.
+
+Application CLIs generated from `@actions.action(..., cli=...)` also support
+remote mode:
+
+```bash
+memuron --base-url https://api.example.app --api-key arth_sk_... memory search --query postgres
+memuron config set --base-url https://api.example.app --api-key arth_sk_...
+```
+
+Remote mode calls the action's HTTP route instead of requiring a local database.
+Install `artha-engine[app]` (or your product package with the same extra) for
+`httpx` support.
+
+## Managed API keys
+
+Products can enable per-tenant API keys with one application hook:
+
+```python
+from artha_engine import ArthaApplication, CompositeAuthProvider, ClerkAuthProvider
+from artha_engine.app.managed_api_keys import ManagedApiKeyAuthProvider
+
+application = ArthaApplication(...)
+store = application.enable_managed_api_keys()
+application.auth_provider = CompositeAuthProvider(
+    primary=ClerkAuthProvider(),
+    fallback=ManagedApiKeyAuthProvider(store=store),
+)
+```
+
+This registers:
+
+```text
+POST   /api-keys
+GET    /api-keys
+DELETE /api-keys/{key_id}
+```
+
+Keys are returned once on create (`arth_sk_...`), stored hashed, scoped, and
+tenant-bound. A bootstrap `ARTHA_API_KEY` env var still works for ops scripts.

artha_engine-0.1.1/README.md

@@ -0,0 +1,104 @@
+# Artha Engine
+
+Artha Engine is the core Python library for building Arthaanu-based memory
+systems. It provides:
+
+- typed Arthaanu representations
+- encoder, lifecycle, decoder, and projection registries
+- an append-only semantic event ledger
+- SQLite and in-memory stores
+- projection replay with watermarks and status
+- typed product actions exposed as HTTP, MCP, and CLI tools
+- Clerk/JWT/API-key authentication adapters
+- portable OCI application builds
+- a small `artha` CLI for inspection and local operation
+
+The engine is intentionally small. Product-specific memory types, profiles,
+retrieval policy, and domain projections should usually live in userland
+packages built on top of the engine.
+
+## Install Locally
+
+From this repository:
+
+```bash
+cd artha_engine
+uv sync
+uv run artha doctor
+```
+
+To run the FastAPI runtime:
+
+```bash
+uv sync --extra server
+uv run artha serve --port 8765
+```
+
+Create product actions with one typed declaration:
+
+```python
+@actions.action(
+    name="memory.search",
+    http=("POST", "/memories/search"),
+    mcp=True,
+    cli="memory search",
+    scopes=["memory:read"],
+)
+def search(input: SearchInput, context: ActionContext) -> SearchOutput:
+    ...
+```
+
+## CLI
+
+```bash
+artha doctor
+artha registry
+artha encode text --input "Artha keeps semantic events canonical."
+artha events --limit 5
+artha objects --limit 5
+artha projections
+artha check
+artha build
+```
+
+Use `--db path/to/artha.db` to point commands at a specific SQLite ledger.
+Most commands support `--json` for agent-friendly output.
+
+Application CLIs generated from `@actions.action(..., cli=...)` also support
+remote mode:
+
+```bash
+memuron --base-url https://api.example.app --api-key arth_sk_... memory search --query postgres
+memuron config set --base-url https://api.example.app --api-key arth_sk_...
+```
+
+Remote mode calls the action's HTTP route instead of requiring a local database.
+Install `artha-engine[app]` (or your product package with the same extra) for
+`httpx` support.
+
+## Managed API keys
+
+Products can enable per-tenant API keys with one application hook:
+
+```python
+from artha_engine import ArthaApplication, CompositeAuthProvider, ClerkAuthProvider
+from artha_engine.app.managed_api_keys import ManagedApiKeyAuthProvider
+
+application = ArthaApplication(...)
+store = application.enable_managed_api_keys()
+application.auth_provider = CompositeAuthProvider(
+    primary=ClerkAuthProvider(),
+    fallback=ManagedApiKeyAuthProvider(store=store),
+)
+```
+
+This registers:
+
+```text
+POST   /api-keys
+GET    /api-keys
+DELETE /api-keys/{key_id}
+```
+
+Keys are returned once on create (`arth_sk_...`), stored hashed, scoped, and
+tenant-bound. A bootstrap `ARTHA_API_KEY` env var still works for ops scripts.

artha_engine-0.1.1/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "artha-engine"
+version = "0.1.1"
+description = "Semantic memory engine with append-only event ledger, Arthaanu representations, and projection replay."
+readme = "README.md"
+authors = [
+    { name = "Alphanimble", email = "rakshith.g@alphanimble.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.13.4",
+    "fastembed>=0.6.0",
+    "litellm>=1.60.0",
+    "psycopg[binary]>=3.2.0",
+]
+keywords = ["memory", "rag", "semantic-events", "projections", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+[project.scripts]
+artha = "artha_engine.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.0.0",
+    "fastapi>=0.115.0",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+]
+app = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "httpx>=0.28.0",
+]
+auth = [
+    "pyjwt[crypto]>=2.10.0,<3",
+]
+mcp = [
+    "mcp>=1.0.0,<2",
+]
+workbench = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: tests that download models or hit external resources",
+]

artha_engine-0.1.1/src/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-0.1.1/src/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",
+]