Metadata-Version: 2.4
Name: parcle
Version: 0.1.0
Summary: Long-term memory for AI agents — a Python client for the Parcle Memory API.
Project-URL: Homepage, https://parcle.ai
Project-URL: Documentation, https://api.parcle.ai
Author: Parcle
License: MIT
License-File: LICENSE
Keywords: agents,ai,llm,memory,parcle,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# Parcle

**Long-term memory for AI agents**

Ingest conversations and files, then ask questions in natural language and get
cited answers back. Give every user a private, persistent agent memory.

</div>

---

## Why Parcle?

LLMs forget everything between calls. Parcle gives every user a private memory you
can write to and search:

- 🧠 **Per-user memory** — scope everything to a `user_id`.
- 💬 **Ingest anything** — chat transcripts and files (PDF, Markdown, text, …) go in the same place.
- 🔎 **Ask, don't query** — search returns a synthesized **answer** with **citations**, not just raw chunks.

## Installation

```bash
pip install parcle
```

## Quickstart

```python
from parcle import Parcle

# Reads PARCLE_API_KEY from the environment if api_key is omitted.
client = Parcle(api_key="pk_live_...")

# 1. Write a conversation into a user's memory.
#    Ingestion is incremental: omit session_id to start a new session, then
#    pass the returned session_id back to append more turns to the same one.
result = client.ingest_dialog(
    user_id="ada",
    messages=[
        {"role": "user", "content": "I'm allergic to peanuts."},
        {"role": "assistant", "content": "Got it — I'll avoid peanuts in suggestions."},
    ],
)
client.ingest_dialog(
    user_id="ada",
    session_id=result.session_id,  # append to the same session
    messages=[
        {"role": "user", "content": "Also, I don't eat shellfish."},
    ],
)

# 2. ...or ingest a file (PDF, Markdown, text, …).
client.ingest_file(user_id="ada", file="diet-notes.pdf")

# 3. Ask a question. You get an answer with confidence and citations.
result = client.search(user_id="ada", query="What food should I avoid?")

print(result.answer)      # "You're allergic to peanuts, so avoid them."
print(result.confidence)  # 0.92
print(result.citations)   # [Citation(type="session", id="...")]
```