luki-sdk-python

Official Python client for the LUKi AI agent & ReMeLife APIs

---

License

This project is licensed under the [Apache 2.0 License with ReMeLife custom clauses]

---

1. What is this?

luki-sdk-python gives you a typed, batteries‑included way to talk to:

• LUKi Core Agent API – chat, tool calls, recommendations
• Memory/ELR endpoints – ingest, search, update Electronic Life Records (ELR®)
• Reporting & Analytics services – pull wellbeing summaries, engagement metrics
• Token/Consent services – (optional) sign data-sharing intents, check CAP → REME status

It wraps our FastAPI gateway with clean Python classes, async support, and CLI helpers, so you can embed LUKi in backends, scripts, or notebooks fast. :contentReference[oaicite:0]{index=0}

---

2. Key Features

• Sync & async clients (requests + httpx)
• Auto-retry / backoff & streaming responses (Server-Sent Events / WebSockets ready)
• Typed models (pydantic) for requests/responses
• RAG helpers to chunk & upload ELR text, then query via embeddings
• Convenience tools: activity recommendations, wellbeing reports, feedback submitters
• CLI for quick testing (luki chat "Hello")

---

3. Install

pip install luki-sdk
# or from source
pip install git+ssh://github.com/REMELife/luki-sdk-python.git

4. Quick Start

from luki_sdk import LukiClient

client = LukiClient(
    base_url="https://api.luki.ai",   # staging/prod URL
    api_key="YOUR_LUKI_API_KEY"       # or use env LUKI_API_KEY
)

# 1) Simple chat
resp = client.chat.send(message="I feel a bit low, any suggestions?")
print(resp.text)

# 2) Recommend activities (uses your stored ELR profile)
acts = client.activities.recommend(user_id="user_123", k=3)
for a in acts:
    print(a.title, "-", a.description)

# 3) Upload ELR chunk
client.elr.upload_text(
    user_id="user_123",
    text="Alice loves gardening and jazz. Wedding in 1975 in Madrid.",
    tags=["interests", "life_event"]
)

Async

import asyncio
from luki_sdk.async_client import AsyncLukiClient

async def main():
    async with AsyncLukiClient(api_key="...", base_url="...") as cli:
        r = await cli.chat.send("Hello LUKi, what's a calming activity?")
        print(r.text)

asyncio.run(main())

5. Authentication

export LUKI_API_KEY=sk_live_xxx

OAuth/JWT flows are supported for enterprise—see /docs/auth.md once enabled.

6. API Surface

Chat / Agent

client.chat.send(
    message: str,
    user_id: str = None,
    context: dict = None,
    stream: bool = False
)
# context: extra metadata (mood tags, session id)
# stream=True: yields tokens progressively

Memory / ELR

client.elr.upload_text(user_id, text, tags=None, sensitivity="normal")
client.elr.upload_file(user_id, path)
client.elr.search(user_id, query, k=5, filters=None)
client.elr.delete(user_id, item_id)

Activities & Cognitive Stimulation

client.activities.recommend(user_id, k=5, mood=None)
client.activities.feedback(activity_id, rating, comment=None)

Wellbeing & Reporting

client.reports.generate(user_id, window_days=7)
client.reports.get(report_id)

Admin / Tokens (optional)

client.tokens.get_caps(user_id)
client.tokens.swap_caps_to_reme(user_id)  # if permitted by backend

Endpoints are versioned (/v1/chat, /v1/elr, …). The SDK tracks minor changes.

7. Configuration

Env Var	Default	Purpose
LUKI_API_KEY	None	Auth token
LUKI_BASE_URL	https://api.luki.ai	API root
LUKI_TIMEOUT	30	Seconds
LUKI_MAX_RETRIES	3	HTTP retries
LUKI_LOG_LEVEL	INFO	SDK logging

(Or pass directly in LukiClient(...).)

8. Streaming & Callbacks

for chunk in client.chat.stream("Tell me a story about my childhood photos"):
    print(chunk.delta, end="")

Register token-level callbacks:

def on_token(tok): print(tok, end="")
client.chat.send("...", stream=True, on_token=on_token)

9. Error Handling

from luki_sdk.errors import LukiHTTPError

try:
    client.elr.upload_text(...)
except LukiHTTPError as e:
    print(e.status_code, e.body)

10. Command Line Interface

luki chat "Suggest a calming music activity"
luki elr upload --user user_123 --file story.txt
luki activities recommend --user user_123 -k 3

Install CLI extras:

pip install luki-sdk[cli]

11. Development

git clone [email protected]:REMELife/luki-sdk-python.git
cd luki-sdk-python
pip install -e ".[dev]"
pytest

We use ruff + black + mypy:

ruff check .
black .
mypy luki_sdk

12. Contributing

PRs welcome (SDK only). For core agent code, see internal repos.
Read CONTRIBUTING.md & sign the CLA.

13. Versioning & Compatibility

Semantic versioning (MAJOR.MINOR.PATCH).
Breaking API changes bump MAJOR; minor additions are non‑breaking.

14. Security

Report vulnerabilities to [email protected].
Never include raw ELR text in issues—use synthetic examples.

15. License

Apache-2.0 © 2025 Singularities Ltd / ReMeLife.

16. Roadmap (SDK)

• WebSocket streaming helper
• Retryable offline ingestion queue
• Pydantic v2 migration (if not already)
• Typed event hooks for tool results