reflect-sdk 0.1.0__tar.gz

reflect_sdk-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Node / TypeScript / JavaScript
+node_modules/
+*.tsbuildinfo
+.cache/
+.parcel-cache/
+.vite/
+.turbo/
+.next/
+.nuxt/
+.output/
+.vercel/
+.netlify/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+.eslintcache
+coverage/
+.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Environment
+.env
+.env.local
+*.local
+
+# OS
+.DS_Store
+Thumbs.db
+benchmark/results

reflect_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: reflect-sdk
+Version: 0.1.0
+Summary: Reflect SDK - Python client for Reflect API
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: ollama>=0.6.1
+Requires-Dist: openai-agents>=0.2.0
+Requires-Dist: openai>=2.28.0
+Provides-Extra: examples
+Requires-Dist: deepagents; extra == 'examples'
+Requires-Dist: exa-py; extra == 'examples'
+Requires-Dist: langchain-openai; extra == 'examples'
+Provides-Extra: langsmith
+Requires-Dist: langsmith>=0.7.0; extra == 'langsmith'

reflect_sdk-0.1.0/docs/.mintignore

@@ -0,0 +1,7 @@
+# Mintlify automatically ignores these files and directories:
+# .git, .github, .claude, .agents, .idea, node_modules,
+# README.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md
+
+# Draft content
+drafts/
+*.draft.mdx

reflect_sdk-0.1.0/docs/ai-tools/claude-code.mdx

@@ -0,0 +1,37 @@
+---
+title: "Claude Code setup"
+description: "Configure Claude Code for Reflect SDK documentation"
+icon: "asterisk"
+---
+
+Set up Claude Code to help you write and maintain the Reflect SDK documentation.
+
+## Prerequisites
+
+- Active Claude subscription (Pro, Max, or API access)
+
+## Setup
+
+<Steps>
+  <Step title="Install Claude Code">
+    ```bash
+    npm install -g @anthropic-ai/claude-code
+    ```
+  </Step>
+
+  <Step title="Install the Mintlify skill">
+    In the docs directory (`packages/sdk/docs`), run:
+
+    ```bash
+    npx skills add https://mintlify.com/docs
+    ```
+
+    This adds Mintlify's component reference, writing standards, and workflow guidance.
+  </Step>
+
+  <Step title="Start writing with Claude Code">
+    ```bash
+    claude
+    ```
+  </Step>
+</Steps>

reflect_sdk-0.1.0/docs/ai-tools/cursor.mdx

@@ -0,0 +1,33 @@
+---
+title: "Cursor setup"
+description: "Configure Cursor for Reflect SDK documentation"
+icon: "arrow-pointer"
+---
+
+Set up Cursor to help you write and maintain the Reflect SDK documentation.
+
+## Prerequisites
+
+- Cursor editor installed
+
+## Setup
+
+<Steps>
+  <Step title="Open the docs directory in Cursor">
+    Open `packages/sdk/docs` where `docs.json` is located.
+  </Step>
+
+  <Step title="Install the Mintlify skill">
+    In the integrated terminal, run:
+
+    ```bash
+    npx skills add https://mintlify.com/docs
+    ```
+
+    This adds Mintlify's component reference, writing standards, and workflow guidance.
+  </Step>
+
+  <Step title="Start writing with Cursor">
+    Open a file and use Cursor's AI features to draft and edit documentation.
+  </Step>
+</Steps>

reflect_sdk-0.1.0/docs/ai-tools/windsurf.mdx

@@ -0,0 +1,33 @@
+---
+title: "Windsurf setup"
+description: "Configure Windsurf for Reflect SDK documentation"
+icon: "water"
+---
+
+Set up Windsurf's Cascade AI assistant to help you write and maintain the Reflect SDK documentation.
+
+## Prerequisites
+
+- Windsurf editor installed
+
+## Setup
+
+<Steps>
+  <Step title="Open the docs directory in Windsurf">
+    Open `packages/sdk/docs` where `docs.json` is located.
+  </Step>
+
+  <Step title="Install the Mintlify skill">
+    In the integrated terminal, run:
+
+    ```bash
+    npx skills add https://mintlify.com/docs
+    ```
+
+    This adds Mintlify's component reference, writing standards, and workflow guidance.
+  </Step>
+
+  <Step title="Start writing with Cascade">
+    Open a file and use Cascade to draft and edit documentation.
+  </Step>
+</Steps>

reflect_sdk-0.1.0/docs/api-reference/introduction.mdx

@@ -0,0 +1,14 @@
+---
+title: "Introduction"
+description: "ReflectClient API reference"
+---
+
+The Reflect SDK reference is generated from docstrings in `reflect_sdk.client`. Each method and data type is documented with signatures and descriptions.
+
+<Card
+  title="ReflectClient"
+  icon="code"
+  href="/api-reference/reflect-client"
+>
+  Full API reference for the Reflect Python client
+</Card>

reflect_sdk-0.1.0/docs/api-reference/reflect-client.mdx

@@ -0,0 +1,84 @@
+---
+title: "ReflectClient"
+description: "API reference for the Reflect Python client."
+---
+
+## Constructor
+
+```python
+ReflectClient(*, base_url: str = 'http://localhost:8000', api_key: str, project_id: str, timeout: float | httpx.Timeout = 60.0) -> None
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | `str` | `"http://localhost:8000"` | Reflect API base URL (e.g. http://localhost:8000). |
+| `api_key` | `str` | `required` | Plaintext API key (e.g. rf_live_...). |
+| `project_id` | `str` | `required` | Project ID from the Reflect console. |
+| `timeout` | `float | httpx.Timeout` | `60.0` | Request timeout in seconds. |
+
+## Instance methods
+
+### health
+
+```python
+def health() -> dict[str, str]
+```
+
+Return the API health status. No authentication required.
+
+### query_memories
+
+```python
+def query_memories(task: str, *, limit: int = 10, lambda_: float = 0.5) -> list[Memory]
+```
+
+Retrieve memories by semantic similarity and Q-value ranking.
+
+### augment_with_memories
+
+```python
+def augment_with_memories(task: str, *, limit: int = 10, lambda_: float = 0.5) -> AugmentedTask
+```
+
+Query memories and format them into the task text for prompt augmentation.
+
+### create_trace
+
+```python
+def create_trace(*, task: str, trajectory: TrajectoryInput, final_response: str, retrieved_memory_ids: Sequence[str] = (), model: str | None = None, metadata: dict[str, Any] | None = None, review_result: str | None = None, feedback_text: str | None = None) -> Trace
+```
+
+Store a trace. Optionally include an inline review.
+
+### list_traces
+
+```python
+def list_traces(*, review_status: str | None = None) -> list[Trace]
+```
+
+List traces for the project.
+
+### get_trace
+
+```python
+def get_trace(trace_id: str) -> Trace
+```
+
+Fetch a single trace by ID.
+
+### review_trace
+
+```python
+def review_trace(trace_id: str, *, result: str, feedback_text: str | None = None) -> Trace
+```
+
+Submit a deferred review for a trace.
+
+## Data types
+
+| Type | Description |
+|------|-------------|
+| `AugmentedTask` | augmented_task, memories |
+| `Memory` | id, task, reflection, q_value, similarity, score, success |
+| `Review` | id, trace_id, result, feedback_text, mode |
+| `Trace` | id, task, trajectory, final_response, retrieved_memory_ids, review_status, model, metadata, created_memory_id, review |

reflect_sdk-0.1.0/docs/development.mdx

@@ -0,0 +1,50 @@
+---
+title: "Development"
+description: "Preview and contribute to the Reflect SDK documentation."
+---
+
+<Info>
+  **Prerequisites**: Node.js 19+ and a docs directory with `docs.json`.
+</Info>
+
+## Preview locally
+
+<Steps>
+  <Step title="Install dependencies">
+    From the `packages/sdk/docs` directory:
+
+    ```bash
+    npm install
+    ```
+  </Step>
+
+  <Step title="Generate API reference">
+    The reference is generated from SDK docstrings. Run:
+
+    ```bash
+    npm run generate
+    ```
+  </Step>
+
+  <Step title="Start the preview server">
+    ```bash
+    npm run dev
+    ```
+
+    Open `http://localhost:3000` to view the docs.
+  </Step>
+</Steps>
+
+<Tip>
+  Use `npm run validate` to check links and build. Use `npm run broken-links` to find broken internal links.
+</Tip>
+
+## Regenerating the reference
+
+When you change docstrings in `packages/sdk/src/reflect_sdk/client.py`, regenerate the reference:
+
+```bash
+npm run generate
+```
+
+The script writes `api-reference/reflect-client.mdx` from the SDK source.

reflect_sdk-0.1.0/docs/docs.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://mintlify.com/schema.json",
+  "theme": "mint",
+  "name": "Reflect SDK",
+  "colors": {
+    "primary": "#2563eb",
+    "light": "#3b82f6",
+    "dark": "#1d4ed8"
+  },
+  "favicon": "/favicon.svg",
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [
+          {
+            "group": "Getting started",
+            "pages": [
+              "index",
+              "quickstart",
+              "installation",
+              "development"
+            ]
+          },
+          {
+            "group": "Core concepts",
+            "pages": [
+              "guides/memories",
+              "guides/traces-and-reviews"
+            ]
+          },
+          {
+            "group": "AI tools",
+            "pages": [
+              "ai-tools/cursor",
+              "ai-tools/claude-code",
+              "ai-tools/windsurf"
+            ]
+          },
+          {
+            "group": "Customization",
+            "pages": [
+              "essentials/settings",
+              "essentials/navigation"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "API reference",
+        "groups": [
+          {
+            "group": "SDK reference",
+            "pages": [
+              "api-reference/introduction",
+              "api-reference/reflect-client"
+            ]
+          }
+        ]
+      }
+    ],
+    "global": {
+      "anchors": [
+        {
+          "anchor": "Console",
+          "href": "https://reflect.starlight-search.com",
+          "icon": "square-terminal"
+        }
+      ]
+    }
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "cursor",
+      "vscode"
+    ]
+  },
+  "footer": {
+    "socials": {}
+  }
+}

reflect_sdk-0.1.0/docs/essentials/navigation.mdx

@@ -0,0 +1,7 @@
+---
+title: "Navigation"
+description: "How navigation is organized in the Reflect SDK docs"
+icon: "map"
+---
+
+The navigation uses tabs: **Guides** and **API reference**. Add new pages in `docs.json` under the appropriate tab and group. Pages not listed in `docs.json` are hidden but still accessible by direct link or search.

reflect_sdk-0.1.0/docs/essentials/settings.mdx

@@ -0,0 +1,7 @@
+---
+title: "Settings"
+description: "Customize the Reflect SDK documentation site"
+icon: "gear"
+---
+
+The `docs.json` file controls the look and feel of the Reflect SDK documentation. Key settings include `name`, `colors`, `logo`, `favicon`, and `navigation`. See the [Mintlify docs](https://mintlify.com/docs) for the full configuration schema.

reflect_sdk-0.1.0/docs/favicon.svg

@@ -0,0 +1,5 @@
+<svg width="502" height="502" viewBox="0 0 502 502" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M501.402 185.33V29.9622C501.402 13.2897 487.876 0 471.453 0H316.156C291.763 0 267.611 4.83243 245.15 14.0144C222.689 23.438 202.16 36.9695 185.012 54.3668L183.804 55.575C161.101 78.5299 144.92 107.042 136.708 138.454C151.441 134.588 166.656 132.655 181.871 132.413C222.447 131.93 262.298 144.978 294.661 169.383C323.885 191.13 346.104 221.092 358.18 255.645C370.739 290.681 372.188 328.859 362.769 364.862C393.925 356.647 422.666 340.457 445.611 317.744L446.818 316.536C463.966 299.38 477.732 278.841 487.151 256.37C496.571 233.898 501.16 209.735 501.16 185.33H501.402Z" fill="#18E299"/>
+<path d="M132.071 182.706C132.312 135.044 151.32 89.3068 184.764 55.1246L55.5569 184.391C55.0756 184.873 54.5942 185.113 54.113 185.595C22.5932 216.888 3.58552 258.774 0.457596 303.066C-2.42971 344.47 8.39746 385.392 31.4959 419.575C33.6992 422.835 39.6774 423.907 43.0459 420.778L122.206 341.822C146.989 317.028 154.689 280.198 142.899 247.219C135.44 226.758 131.831 204.852 132.071 182.706Z" fill="#0C8C5E"/>
+<path d="M446.067 316.547C421.284 340.86 390.245 357.71 356.56 365.172C322.634 372.635 287.506 370.468 254.783 358.914C254.783 358.914 254.542 358.914 254.301 358.914C221.338 347.118 184.525 354.821 159.742 379.375L80.5808 458.331C77.2123 461.701 77.6935 467.238 81.7838 469.885C115.95 492.754 156.855 503.827 198.24 500.938C242.512 497.809 284.137 478.792 315.656 447.258L316.859 446.054L446.067 316.788V316.547Z" fill="#0C8C5E"/>
+</svg>

reflect_sdk-0.1.0/docs/guides/memories.mdx

@@ -0,0 +1,51 @@
+---
+title: "Memories"
+description: "Query and augment tasks with Reflect memories."
+---
+
+Memories are stored reflections from past tasks and reviews. The Reflect API retrieves them by semantic similarity and Q-value ranking, so you can reuse successful patterns and avoid known failures.
+
+## Query memories
+
+Use `query_memories` to fetch relevant memories for a task:
+
+```python
+memories = client.query_memories(
+    task="How do I handle rate limits in an API client?",
+    limit=10,
+    lambda_=0.5,
+)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `task` | `str` | required | The task description to search against. Embeddings are computed from this text. |
+| `limit` | `int` | `10` | Maximum number of memories to return. |
+| `lambda_` | `float` | `0.5` | Blend weight between semantic similarity (1.0 = pure similarity) and Q-value ranking (0.0 = pure Q-value). |
+
+Each returned `Memory` has:
+
+- `id`, `task`, `reflection` – the stored content
+- `q_value` – learned Q-value from reviews
+- `similarity` – embedding similarity to the query
+- `score` – blended ranking score
+- `success` – `True`/`False`/`None` from past reviews
+
+## Augment with memories
+
+`augment_with_memories` retrieves memories and formats them into a text block you can append to your prompt:
+
+```python
+from reflect_sdk import ReflectClient
+
+client = ReflectClient(api_key="...", project_id="...")
+augmented = client.augment_with_memories(
+    task="Implement exponential backoff for retries",
+    limit=5,
+)
+
+# augmented.augmented_task = task + "\n\nRelevant memories:\n\n" + formatted blocks
+# augmented.memories = list of Memory objects
+```
+
+Memories are grouped by `success`: successful, failed, and other. Each block includes the past task and reflection.

reflect_sdk-0.1.0/docs/guides/traces-and-reviews.mdx

@@ -0,0 +1,67 @@
+---
+title: "Traces and reviews"
+description: "Record trajectories and submit reviews for learning."
+---
+
+Traces capture the full trajectory of an AI run (task, steps, final response, retrieved memories). Reviews mark the outcome (success or failure) and optionally include feedback. Reviews update Q-values and create new reflection memories.
+
+## Create a trace
+
+Use `create_trace` to store a trajectory:
+
+```python
+from reflect_sdk import ReflectClient
+
+client = ReflectClient(api_key="...", project_id="...")
+trace = client.create_trace(
+    task="Parse the CSV and return the top 5 rows",
+    trajectory=[
+        {"role": "user", "content": "Parse the CSV..."},
+        {"role": "assistant", "content": "I'll use pandas..."},
+    ],
+    final_response="Here are the top 5 rows: ...",
+    retrieved_memory_ids=["mem_abc", "mem_def"],
+    model="gpt-4",
+    metadata={"source": "cli"},
+)
+```
+
+You can pass `trajectory` as a list of message dicts or a JSON string.
+
+## Inline review
+
+Include a review when creating the trace:
+
+```python
+trace = client.create_trace(
+    task="...",
+    trajectory=[...],
+    final_response="...",
+    retrieved_memory_ids=["mem_abc"],
+    review_result="success",
+    feedback_text="Correct output format.",
+)
+```
+
+`review_result` must be `"success"` or `"failure"`. The review is applied immediately; no separate `review_trace` call is needed.
+
+## Deferred review
+
+Create the trace first, then submit a review later:
+
+```python
+trace = client.create_trace(task="...", trajectory=[...], final_response="...")
+# ... later, after human feedback ...
+updated = client.review_trace(
+    trace_id=trace.id,
+    result="failure",
+    feedback_text="Wrong column order.",
+)
+```
+
+## List and fetch traces
+
+```python
+traces = client.list_traces(review_status="pending")  # or "reviewed" or None for all
+trace = client.get_trace(trace_id="tr_xyz")
+```

reflect_sdk-0.1.0/docs/index.mdx

@@ -0,0 +1,71 @@
+---
+title: "Introduction"
+description: "Overview of the Reflect SDK for Python."
+---
+
+The Reflect SDK is a Python client for the Reflect API. It lets you query memories, augment tasks with learned reflections, and record traces with reviews so your AI improves from feedback.
+
+## What Reflect does
+
+Reflect combines semantic search with Q-learning to surface relevant past experiences. When you query memories for a task, the API blends embedding similarity with learned Q-values so high-scoring reflections rank higher over time.
+
+The workflow:
+
+1. **Query memories** – Retrieve similar past reflections for a task.
+2. **Augment your prompt** – Append successful and failed memories to the task text.
+3. **Generate a response** – Your LLM uses the augmented context.
+4. **Record a trace** – Store the trajectory and final response.
+5. **Submit a review** – Mark success or failure with optional feedback.
+
+Reviews update Q-values in the vector store and create new reflection memories. Future queries automatically favor reflections that led to success.
+
+## Get started
+
+<Card
+  title="Quickstart"
+  icon="rocket"
+  href="/quickstart"
+  horizontal
+>
+  Sign in to Reflect, create a project and API key, then use the SDK.
+</Card>
+
+## Requirements
+
+- Python 3.12+
+- An account on the [Reflect console](https://reflect.starlight-search.com)
+- A project and API key created in the console (see [Quickstart](/quickstart))
+- The Reflect API `base_url` for your environment
+
+## Next steps
+
+<Columns cols={2}>
+  <Card
+    title="Memories"
+    icon="brain"
+    href="/guides/memories"
+  >
+    Query and augment tasks with past reflections.
+  </Card>
+  <Card
+    title="Traces and reviews"
+    icon="clipboard-list"
+    href="/guides/traces-and-reviews"
+  >
+    Record trajectories and submit reviews for learning.
+  </Card>
+  <Card
+    title="API reference"
+    icon="code"
+    href="/api-reference/reflect-client"
+  >
+    Full ReflectClient reference from docstrings.
+  </Card>
+  <Card
+    title="Installation"
+    icon="download"
+    href="/installation"
+  >
+    Install the Reflect SDK with pip.
+  </Card>
+</Columns>

reflect_sdk-0.1.0/docs/installation.mdx

@@ -0,0 +1,24 @@
+---
+title: "Installation"
+description: "Install the Reflect SDK for Python."
+---
+
+Install the Reflect SDK with pip:
+
+```bash
+pip install reflect-sdk
+```
+
+## Optional dependencies
+
+For LangSmith tracing:
+
+```bash
+pip install reflect-sdk[langsmith]
+```
+
+For example scripts (DeepAgents, Exa, LangChain):
+
+```bash
+pip install reflect-sdk[examples]
+```