parcle 0.1.0__tar.gz

parcle-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv
+venv
+env
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

parcle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parcle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parcle-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+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="...")]
+```

parcle-0.1.0/README.md

@@ -0,0 +1,64 @@
+<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="...")]
+```

parcle-0.1.0/example.py

@@ -0,0 +1,90 @@
+"""End-to-end example against the live Parcle Memory API.
+
+Run it with the SDK installed (``pip install -e .``)::
+
+    python example.py
+
+It walks the full memory lifecycle for one user: create the user, ingest a
+dialog and a file, wait for both to become searchable, ask a question, then
+inspect and clean up the stored sources.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+
+from parcle import Parcle
+
+# The API key and base URL. Prefer env vars; fall back to the literals so this
+# example is runnable as-is. This key lives on the backend.parcle.ai environment.
+API_KEY = os.environ.get("PARCLE_API_KEY", "pmem_9je7QBamPK9b3a0qFXCvCMkk5U9iQaIrkGp4lMyi9Kg")
+BASE_URL = os.environ.get("PARCLE_BASE_URL", "https://backend.parcle.ai")
+
+USER_ID = "ada"
+
+
+def main() -> None:
+    # Search synthesizes an answer with an LLM, so allow a generous timeout.
+    with Parcle(api_key=API_KEY, base_url=BASE_URL, timeout=120.0) as client:
+        # 1. Create (or update) the user this memory belongs to.
+        user = client.create_user(USER_ID, name="Ada", timezone="America/New_York")
+        print(f"user: {user.user_id} (is_new={user.is_new})")
+
+        # 2. Ingest a conversation. Ingestion is incremental: keep the
+        #    session_id to append more turns to the same session later.
+        dialog = client.ingest_dialog(
+            user_id=USER_ID,
+            messages=[
+                {"role": "user", "content": "I'm allergic to peanuts."},
+                {"role": "assistant", "content": "Got it — I'll avoid peanuts."},
+            ],
+            tag={"app": "meal-planner"},
+        )
+        print(f"dialog: session={dialog.session_id} event={dialog.event_id}")
+
+        client.ingest_dialog(
+            user_id=USER_ID,
+            session_id=dialog.session_id,  # append to the same session
+            messages=[{"role": "user", "content": "Also, I don't eat shellfish."}],
+        )
+
+        # 3. Ingest a file into the same memory.
+        with tempfile.NamedTemporaryFile(
+            "w", suffix=".md", delete=False, encoding="utf-8"
+        ) as fh:
+            fh.write("# Diet notes\n\nVegetarian. Avoid nuts and shellfish.\n")
+            notes_path = fh.name
+        try:
+            uploaded = client.ingest_file(
+                user_id=USER_ID, file=notes_path, tag={"source": "diet-notes"}
+            )
+            print(f"file: id={uploaded.file_id} event={uploaded.event_id}")
+
+            # 4. Wait until both writes are searchable.
+            client.wait_until_ready(USER_ID, dialog.event_id)
+            client.wait_until_ready(USER_ID, uploaded.event_id)
+            print("ingestion ready")
+
+            # 5. Ask a question — you get an answer with confidence + citations.
+            result = client.search(
+                user_id=USER_ID,
+                query="What food should I avoid?",
+                tag_filter={"app": "meal-planner"},
+            )
+            print(f"\nanswer:     {result.answer}")
+            print(f"confidence: {result.confidence}")
+            for c in result.citations:
+                print(f"citation:   {c.type} {c.id}")
+
+            # 6. Inspect what's stored for this user.
+            print("\nsources:")
+            for source in client.iter_sources(USER_ID):
+                label = source.name or source.id
+                print(f"  - {source.type}: {label}  tag={source.tag}")
+        finally:
+            os.unlink(notes_path)
+
+
+if __name__ == "__main__":
+    main()

parcle-0.1.0/parcle/__init__.py

@@ -0,0 +1,79 @@
+"""Parcle — long-term memory for AI agents.
+
+Ingest conversations and files into a per-user memory, then ask questions in
+natural language and get cited answers back.
+
+    from parcle import Parcle
+
+    client = Parcle(api_key="pk_live_...")
+    client.ingest_dialog(user_id="ada", messages=[{"role": "user", "content": "..."}])
+    result = client.search(user_id="ada", query="What food should I avoid?")
+    print(result.answer, result.confidence, result.citations)
+"""
+
+from __future__ import annotations
+
+from .client import Parcle
+from .exceptions import (
+    AuthenticationError,
+    FileTooLargeError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    ParcleAPIError,
+    ParcleConfigError,
+    ParcleConnectionError,
+    ParcleError,
+    ParcleTimeoutError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnsupportedFileTypeError,
+    ValidationError,
+)
+from .models import (
+    Citation,
+    DeleteResult,
+    Event,
+    IngestDialogResult,
+    IngestFileResult,
+    Message,
+    SearchResult,
+    Session,
+    Source,
+    SourcesPage,
+    User,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Parcle",
+    "__version__",
+    # models
+    "Citation",
+    "DeleteResult",
+    "Event",
+    "IngestDialogResult",
+    "IngestFileResult",
+    "Message",
+    "SearchResult",
+    "Session",
+    "Source",
+    "SourcesPage",
+    "User",
+    # exceptions
+    "ParcleError",
+    "ParcleConfigError",
+    "ParcleConnectionError",
+    "ParcleTimeoutError",
+    "ParcleAPIError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "NotFoundError",
+    "FileTooLargeError",
+    "UnsupportedFileTypeError",
+    "ValidationError",
+    "RateLimitError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+]