Metadata-Version: 2.3
Name: artha-engine
Version: 0.1.3
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.
