Metadata-Version: 2.4
Name: engramme
Version: 0.1.1
Summary: Python SDK for Engramme's human memory API
Author-email: Engramme <support@engramme.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://engramme.com
Project-URL: Documentation, https://docs.engramme.com
Project-URL: Repository, https://github.com/engramme/engramme-python
Project-URL: Issues, https://github.com/engramme/engramme-python/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Engramme Python SDK

Engramme is the API to augment human memory.

Engramme turns documents, notes, transcripts, and other lived context into structured episodic memories. Its Large Memory Models (LMMs) extract who was involved, what happened, when it happened, and how experiences connect, so applications can help people recall relevant memories naturally.

Use the Python SDK to build with Engramme from notebooks, scripts, backend services, and internal tools.

The SDK currently supports the tested public workflow:

- Authenticate with an Engramme API key.
- Upload content with `memorize`.
- Retrieve raw memories with `recall`.
- Check API health.

It does not expose `ask()` or feedback submission yet. Feedback is currently handled by the Engramme webapp while we keep the public SDK contract focused and stable.

## Installation

```bash
pip install engramme
```

## Authentication

Pass an API key directly:

```python
from engramme import Engramme

client = Engramme(api_key="eng_sk_...")
```

Or set an environment variable:

```bash
export ENGRAMME_API_KEY="eng_sk_..."
```

Then initialize without arguments:

```python
from engramme import Engramme

client = Engramme()
```

You can also save a key locally:

```bash
engramme login
engramme whoami
engramme profiles
engramme logout
```

Local credentials are stored in `~/.engramme/config.yaml`. Override that path with:

```bash
export ENGRAMME_CONFIG_PATH="/path/to/config.yaml"
```

## Quickstart

```python
from engramme import Engramme

client = Engramme()

print(client.health_check())

upload = client.memorize(
    file=b"Meeting notes about the Q4 roadmap and launch timeline.",
    user_name="Sanket",
    source_type="text",
    filename="meeting-notes.txt",
)

print(upload["item_id"])

results = client.recall("Q4 roadmap launch timeline")

for memory in results.get("memories", []):
    print(memory)
```

Memorization starts asynchronous processing. A successful `memorize` response means the upload was accepted and a workflow started; the content may not be immediately recallable.

## API

### `Engramme(...)`

```python
client = Engramme(
    api_key=None,
    profile=None,
    base_url="https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev",
    timeout=30,
)
```

API key resolution order:

1. Explicit `api_key`
2. `ENGRAMME_API_KEY`
3. Active profile in `~/.engramme/config.yaml`

### `memorize(...)`

Upload content for memory extraction and indexing.

```python
client.memorize(
    file="notes.txt",
    user_name="Sanket",
    item_id="optional-stable-id",
    source_type="text",
)
```

`file` can be:

- A path string
- A `pathlib.Path`
- Raw bytes

When passing bytes, use `filename` if you want a specific uploaded filename:

```python
client.memorize(
    file=b"Some text",
    user_name="Sanket",
    source_type="text",
    filename="note.txt",
)
```

### `recall(...)`

Retrieve memories by semantic similarity.

```python
results = client.recall(
    "meetings about roadmap planning",
    source="text",
    enable_trace=True,
    alpha=0.5,
)
```

Arguments:

- `text`: Query text, max 1000 characters.
- `source`: Optional source filter.
- `enable_trace`: Include trace metadata when the API supports it.
- `alpha`: Optional hybrid search weight between `0.0` and `1.0`.

### `health_check()`

```python
ok = client.health_check()
```

Returns `True` when `GET /v1/health` returns HTTP 200.

## Feedback

Feedback is not part of the public SDK surface yet.

The Engramme webapp supports rich recall feedback, including overall ratings, memory-level ratings, comments, and issue codes. That flow is currently owned by the webapp backend, not the Core API gateway used by this SDK.

When a stable SDK-facing feedback endpoint exists, the SDK should expose a simple method that lets developers rate recall quality without knowing the webapp telemetry schema.

## Errors

The SDK raises:

- `AuthenticationError`
- `RateLimitError`
- `NotFoundError`
- `ValidationError`
- `APIError`

All inherit from `EngrammeError`.

