Metadata-Version: 2.4
Name: zenmem
Version: 0.4.4
Summary: zenmem LLM SDK — sessions, scoped memory, multi-provider LLM calls
Author-email: zenmem <kartik.p@talowiz.com>
License-Expression: MIT
Project-URL: Repository, https://bitbucket.org/shubhanshu_talowiz/vmi-libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: openai
Requires-Dist: openai>=1.30.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.7.0; extra == "gemini"
Provides-Extra: all
Requires-Dist: openai>=1.30.0; extra == "all"
Requires-Dist: anthropic>=0.30.0; extra == "all"
Requires-Dist: google-generativeai>=0.7.0; extra == "all"
Provides-Extra: test-app
Requires-Dist: python-dotenv>=1.0.0; extra == "test-app"
Dynamic: license-file

# zenmem LLM SDK (Python)

A minimal SDK for building AI features with memory. Start a session, call an
LLM, and let it remember things — at whatever scope makes sense: this
conversation, this project, or the whole company.

```bash
pip install zenmem
pip install "zenmem[all]"       # + openai, anthropic, google-generativeai
```

```python
from zenmem import ZenmemClient, ZenmemConfig

client = ZenmemClient(ZenmemConfig(
    endpoint="http://203.0.113.10:6636",   # your zenmem deployment — IP:port
    accessToken="<your token>",
    companyCode="WPCORP4812",
))

sessionId = client.startSession()

result = client.callLLM(
    rawPrompt="What should I learn next?",
    provider="OPENAI", model="gpt-4o-mini",
    scope="session", sessionId=sessionId,
    passMemory=True, saveInMemory=True,
)
print(result.output)

client.endSession(sessionId)
```

That `callLLM` pulled relevant memory into context, called the model, and
wrote a summary of the exchange back — one call.

Requires Python 3.11+. Provider keys come from `ZenmemConfig` fields or the
matching environment variable: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
`GOOGLE_API_KEY`, `DEEPSEEK_API_KEY`.

`endpoint` is required — one host:port for everything the SDK talks to.
There is no default; every client must say explicitly which deployment it's
pointed at.

---

## The basics

Everything in this SDK is one of four things:

| | |
| --- | --- |
| `client.startSession()` / `client.endSession(id)` | begin/end a conversation |
| `client.callLLM(...)` | call a model, optionally with memory in and out |
| `client.addMemory(text, scope=...)` | remember something |
| `client.fetchMemory(query, scope=...)` | recall something |

## Scope

Every memory-touching call takes a `scope`:

| scope | meaning |
| --- | --- |
| `"session"` | this conversation only — requires `sessionId` |
| `"project"` | shared across everything running under your configured project |
| `"company"` | shared company-wide, no project partition |

```python
client.addMemory("the user prefers Python", scope="session", sessionId=sessionId)
client.addMemory("our support hours are 9-5 ET", scope="company")

memory = client.fetchMemory("what does the user prefer?", scope="session", sessionId=sessionId)
memory.memoryText   # plain-text block, ready for an LLM prompt
memory.dataNodes    # [DataNode(id, text, score, metadata), ...]
```

`scope="project"` reads/writes are partitioned by `ZenmemConfig.companyProjectCode`,
so several projects can share one account without seeing each other's memory.
Pass `projectId="OTHER_PROJECT"` to target a different project for one call.

## callLLM

```python
result = client.callLLM(
    rawPrompt="...",                 # or promptId="PROMPT-XXXX"
    provider="OPENAI", model="gpt-4o-mini",   # not needed with promptId
    inputParams={"question": "..."},
    scope="session", sessionId=sessionId,
    passMemory=True,                 # inject memory from `scope` as context
    saveInMemory=True,               # write a summary of this exchange back
)
result.output, result.summary, result.inputTokens, result.outputTokens
```

Memory retrieval and summarization are non-fatal — if they fail, the model
call still goes through without that context.

## Sessions

```python
sessionId = client.startSession()          # or startSession("my-own-id")
client.addMemory("...", scope="session", sessionId=sessionId)
client.callLLM(rawPrompt="...", provider="OPENAI", model="gpt-4o-mini",
               scope="session", sessionId=sessionId, passMemory=True)
client.endSession(sessionId)               # promotes its memory to longterm
```

A closed session id cannot be reused — always start a fresh one for a new
conversation.

## Module-level API

For scripts that only need one client:

```python
import zenmem

zenmem.init(config)
sessionId = zenmem.startSession()
zenmem.addMemory("...", scope="session", sessionId=sessionId)
zenmem.callLLM(rawPrompt="...", provider="OPENAI", model="gpt-4o-mini")
```

## Errors

All SDK errors derive from `ZenmemError`, so one `except` catches everything:

| Exception | Raised when |
| --- | --- |
| `ZenmemConfigError` | Missing token, key, or an invalid `scope`. |
| `ZenmemApiError` | A backend call failed (carries `statusCode`, `responseBody`). |
| `ProviderError` | The LLM provider call failed. |

## Renamed from VMI

This library was previously `vmi-llm-sdk`. **Nothing breaks on upgrade** — the
old names are still exported as aliases to the same objects.

| Old | New |
| --- | --- |
| `pip install vmi-llm-sdk` | `pip install zenmem` |
| `import llm_sdk` | `import zenmem` (both work) |
| `VmiClient` / `VmiConfig` / `VmiTransaction` | `ZenmemClient` / `ZenmemConfig` / `ZenmemTransaction` |
| `VmiError` / `VmiConfigError` / `VmiApiError` | `ZenmemError` / `ZenmemConfigError` / `ZenmemApiError` |
| `VMI_*` env vars | `ZENMEM_*` (old names read as a fallback) |

## Full documentation

The complete reference **installs with the package**:

```python
import zenmem
print(zenmem.docs_path())
```

| Page | Contents |
| --- | --- |
| `docs/configuration.md` | Every `ZenmemConfig` field |
| `docs/memory.md` | `addMemory` / `fetchMemory` reference |
| `docs/llm-calls.md` | `callLLM` parameters and pipeline |
| `docs/scoping.md` | session / project / company memory |
| `docs/sessions.md` | Session lifecycle |
| `docs/transactions.md` | Grouping several writes into one commit/rollback |
| `docs/models.md` | Typed results and exception hierarchy |

## License

MIT. The full text ships in the package as `LICENSE`.
