Metadata-Version: 2.4
Name: engramme
Version: 0.1.0
Summary: Official Python SDK for the Engramme 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

Official Python SDK for the Engramme API.

The SDK currently supports the tested memory workflow:

- Authenticate with an Engramme API key
- Upload content with `memorize`
- Retrieve memories with `recall`
- Check API health
- Trigger feedback enrichment for an existing feedback document

It does not expose `ask()` and does not submit webapp telemetry feedback.

## Installation

```bash
pip install engramme
```

For local development from this repo:

```bash
pip install -e ".[dev]"
```

## 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`.

### `enrich_feedback(...)`

Trigger feature enrichment for an existing feedback document.

```python
client.enrich_feedback(
    feedback_id="feedback_doc_id",
    trace_id="trace_id_from_recall",
)
```

This maps to `POST /v1/feedback/enrich`. It does not create user feedback. Rich webapp feedback submission is currently an internal webapp telemetry flow, not a public SDK method.

### `health_check()`

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

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

## Errors

The SDK raises:

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

All inherit from `EngrammeError`.

## Development

```bash
pip install -e ".[dev]"
python3 -m pytest
```

Run integration tests with:

```bash
export ENGRAMME_TEST_API_KEY="eng_sk_..."
python3 -m pytest tests/test_integration.py -v
```

Build and check the package:

```bash
python3 -m build
python3 -m twine check dist/*
```
