warm-memory 0.2.1__tar.gz → 0.2.2__tar.gz

{warm_memory-0.2.1 → warm_memory-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: warm-memory
-Version: 0.2.1
+Version: 0.2.2
 Summary: Capacity-bounded warm memory for LLM agents, with a LangGraph BaseStore implementation, embeddings-based importance scoring, and a comparative benchmark.
 Author: Vivek Singh
 License-Expression: MIT
@@ -34,6 +34,7 @@ Dynamic: license-file
 
 # WarmMemory
 
+[![PyPI](https://img.shields.io/pypi/v/warm-memory.svg)](https://pypi.org/project/warm-memory/)
 [![CI](https://github.com/vsingh45/WarmMemory/actions/workflows/ci.yml/badge.svg)](https://github.com/vsingh45/WarmMemory/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -116,7 +117,15 @@ The benchmark models a practical split:
 ## Installation
 
 ```bash
-python3 -m pip install -e .
+pip install warm-memory
+# or with the LangGraph integration:
+pip install warm-memory[langgraph]
+```
+
+Or install from source for development:
+
+```bash
+python3 -m pip install -e ".[langgraph]"
 ```
 
 ## Quick Start
@@ -196,11 +205,49 @@ The HTML guide explains:
 - how to use the package,
 - and how the components fit together.
 
-## Architecture Preview
-
-![WarmMemory Architecture](docs/warm_memory_architecture.svg)
-
-For a richer visual walkthrough, open `docs/warm_memory_guide.html` locally or publish it with GitHub Pages.
+## Architecture
+
+![WarmMemory architecture](https://raw.githubusercontent.com/vsingh45/WarmMemory/main/docs/warm_memory_architecture.drawio.svg)
+
+The pipeline:
+
+1. **Agent Runtime** receives the user query in a per-user namespace and
+   triggers two reads: a fast lookup against **WarmMemory** (the in-process
+   working set) and a **Retrieval Ranker** scoring pass over those rows
+   (`KeywordImportanceScorer` by default; swap in `EmbeddingsImportanceScorer`
+   for semantic ranking).
+2. **Warm Hit?** checks the best score against the configured threshold.
+3. **Green path (warm hit):** results flow to **Prompt Builder**, which injects
+   only the top-K rows into the system prompt before invoking the **LLM**.
+   The vector tier is never touched.
+4. **Orange path (warm miss):** the query falls through to **Long-Term Memory**
+   (LangGraph's `InMemoryStore` with an embedding index, `PostgresStore`, or
+   any `BaseStore`) and the LLM consumes those results as fallback.
+5. **Dashed write-back loop:** the LLM response is captured by the decorator
+   and written back to WarmMemory (and mirrored to Long-Term Memory by the
+   `memory_write` node), so future turns can recall it.
+
+On the synthetic benchmark, ~50% of turns take the green path, eliminating
+that many vector-store calls.
+
+The diagram ships in two paired formats:
+
+- **[`docs/warm_memory_architecture.drawio.svg`](docs/warm_memory_architecture.drawio.svg)** —
+  the rendered SVG that GitHub displays inline. The decision arrows flow
+  ("marching ants" SMIL animation) so the hot/cold paths read at a glance.
+  Open the file directly in a browser to see the animation; GitHub also
+  renders the animation when displaying the SVG.
+- **[`docs/warm_memory_architecture.drawio`](docs/warm_memory_architecture.drawio)** —
+  the editable mxgraph source. Open at [diagrams.net](https://app.diagrams.net)
+  (File → Open from device) to edit; re-export the SVG when done.
+
+The `.drawio.svg` also embeds the mxgraph XML in its `content` attribute, so
+either file round-trips through the editor — they're kept in sync from the
+same generator script.
+
+For a richer narrated walkthrough, open
+[`docs/warm_memory_guide.html`](docs/warm_memory_guide.html) locally or publish
+it with GitHub Pages.
 
 ## Development
 
@@ -213,10 +260,10 @@ python3 -m unittest discover -s tests -v
 ## LangGraph Integration
 
 WarmMemory ships an optional `warm_memory.langgraph` module that plugs directly
-into the LangGraph ecosystem. Install the extra:
+into the LangGraph ecosystem. Install with the extra:
 
 ```bash
-python3 -m pip install -e ".[langgraph]"
+pip install warm-memory[langgraph]
 ```
 
 ### Drop-in `BaseStore`
@@ -297,8 +344,9 @@ to compare against real semantic search.
 - record actual model latency and token usage from a live LLM pipeline
 - add charts and experiment summaries for publication-style reporting
 - TTL support for the LangGraph `BaseStore`
-- publish `warm-memory` to PyPI and propose inclusion in LangGraph's third-party
-  store list
+- ~~publish `warm-memory` to PyPI~~ ([live at v0.2.1](https://pypi.org/project/warm-memory/))
+- propose inclusion in LangGraph's third-party store list (LangChain Forum
+  proposal in flight)
 
 ## License
 

{warm_memory-0.2.1 → warm_memory-0.2.2}/README.md

@@ -1,5 +1,6 @@
 # WarmMemory
 
+[![PyPI](https://img.shields.io/pypi/v/warm-memory.svg)](https://pypi.org/project/warm-memory/)
 [![CI](https://github.com/vsingh45/WarmMemory/actions/workflows/ci.yml/badge.svg)](https://github.com/vsingh45/WarmMemory/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -82,7 +83,15 @@ The benchmark models a practical split:
 ## Installation
 
 ```bash
-python3 -m pip install -e .
+pip install warm-memory
+# or with the LangGraph integration:
+pip install warm-memory[langgraph]
+```
+
+Or install from source for development:
+
+```bash
+python3 -m pip install -e ".[langgraph]"
 ```
 
 ## Quick Start
@@ -162,11 +171,49 @@ The HTML guide explains:
 - how to use the package,
 - and how the components fit together.
 
-## Architecture Preview
-
-![WarmMemory Architecture](docs/warm_memory_architecture.svg)
-
-For a richer visual walkthrough, open `docs/warm_memory_guide.html` locally or publish it with GitHub Pages.
+## Architecture
+
+![WarmMemory architecture](https://raw.githubusercontent.com/vsingh45/WarmMemory/main/docs/warm_memory_architecture.drawio.svg)
+
+The pipeline:
+
+1. **Agent Runtime** receives the user query in a per-user namespace and
+   triggers two reads: a fast lookup against **WarmMemory** (the in-process
+   working set) and a **Retrieval Ranker** scoring pass over those rows
+   (`KeywordImportanceScorer` by default; swap in `EmbeddingsImportanceScorer`
+   for semantic ranking).
+2. **Warm Hit?** checks the best score against the configured threshold.
+3. **Green path (warm hit):** results flow to **Prompt Builder**, which injects
+   only the top-K rows into the system prompt before invoking the **LLM**.
+   The vector tier is never touched.
+4. **Orange path (warm miss):** the query falls through to **Long-Term Memory**
+   (LangGraph's `InMemoryStore` with an embedding index, `PostgresStore`, or
+   any `BaseStore`) and the LLM consumes those results as fallback.
+5. **Dashed write-back loop:** the LLM response is captured by the decorator
+   and written back to WarmMemory (and mirrored to Long-Term Memory by the
+   `memory_write` node), so future turns can recall it.
+
+On the synthetic benchmark, ~50% of turns take the green path, eliminating
+that many vector-store calls.
+
+The diagram ships in two paired formats:
+
+- **[`docs/warm_memory_architecture.drawio.svg`](docs/warm_memory_architecture.drawio.svg)** —
+  the rendered SVG that GitHub displays inline. The decision arrows flow
+  ("marching ants" SMIL animation) so the hot/cold paths read at a glance.
+  Open the file directly in a browser to see the animation; GitHub also
+  renders the animation when displaying the SVG.
+- **[`docs/warm_memory_architecture.drawio`](docs/warm_memory_architecture.drawio)** —
+  the editable mxgraph source. Open at [diagrams.net](https://app.diagrams.net)
+  (File → Open from device) to edit; re-export the SVG when done.
+
+The `.drawio.svg` also embeds the mxgraph XML in its `content` attribute, so
+either file round-trips through the editor — they're kept in sync from the
+same generator script.
+
+For a richer narrated walkthrough, open
+[`docs/warm_memory_guide.html`](docs/warm_memory_guide.html) locally or publish
+it with GitHub Pages.
 
 ## Development
 
@@ -179,10 +226,10 @@ python3 -m unittest discover -s tests -v
 ## LangGraph Integration
 
 WarmMemory ships an optional `warm_memory.langgraph` module that plugs directly
-into the LangGraph ecosystem. Install the extra:
+into the LangGraph ecosystem. Install with the extra:
 
 ```bash
-python3 -m pip install -e ".[langgraph]"
+pip install warm-memory[langgraph]
 ```
 
 ### Drop-in `BaseStore`
@@ -263,8 +310,9 @@ to compare against real semantic search.
 - record actual model latency and token usage from a live LLM pipeline
 - add charts and experiment summaries for publication-style reporting
 - TTL support for the LangGraph `BaseStore`
-- publish `warm-memory` to PyPI and propose inclusion in LangGraph's third-party
-  store list
+- ~~publish `warm-memory` to PyPI~~ ([live at v0.2.1](https://pypi.org/project/warm-memory/))
+- propose inclusion in LangGraph's third-party store list (LangChain Forum
+  proposal in flight)
 
 ## License
 

{warm_memory-0.2.1 → warm_memory-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "warm-memory"
-version = "0.2.1"
+version = "0.2.2"
 description = "Capacity-bounded warm memory for LLM agents, with a LangGraph BaseStore implementation, embeddings-based importance scoring, and a comparative benchmark."
 readme = "README.md"
 requires-python = ">=3.11"

{warm_memory-0.2.1 → warm_memory-0.2.2}/warm_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: warm-memory
-Version: 0.2.1
+Version: 0.2.2
 Summary: Capacity-bounded warm memory for LLM agents, with a LangGraph BaseStore implementation, embeddings-based importance scoring, and a comparative benchmark.
 Author: Vivek Singh
 License-Expression: MIT
@@ -34,6 +34,7 @@ Dynamic: license-file
 
 # WarmMemory
 
+[![PyPI](https://img.shields.io/pypi/v/warm-memory.svg)](https://pypi.org/project/warm-memory/)
 [![CI](https://github.com/vsingh45/WarmMemory/actions/workflows/ci.yml/badge.svg)](https://github.com/vsingh45/WarmMemory/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -116,7 +117,15 @@ The benchmark models a practical split:
 ## Installation
 
 ```bash
-python3 -m pip install -e .
+pip install warm-memory
+# or with the LangGraph integration:
+pip install warm-memory[langgraph]
+```
+
+Or install from source for development:
+
+```bash
+python3 -m pip install -e ".[langgraph]"
 ```
 
 ## Quick Start
@@ -196,11 +205,49 @@ The HTML guide explains:
 - how to use the package,
 - and how the components fit together.
 
-## Architecture Preview
-
-![WarmMemory Architecture](docs/warm_memory_architecture.svg)
-
-For a richer visual walkthrough, open `docs/warm_memory_guide.html` locally or publish it with GitHub Pages.
+## Architecture
+
+![WarmMemory architecture](https://raw.githubusercontent.com/vsingh45/WarmMemory/main/docs/warm_memory_architecture.drawio.svg)
+
+The pipeline:
+
+1. **Agent Runtime** receives the user query in a per-user namespace and
+   triggers two reads: a fast lookup against **WarmMemory** (the in-process
+   working set) and a **Retrieval Ranker** scoring pass over those rows
+   (`KeywordImportanceScorer` by default; swap in `EmbeddingsImportanceScorer`
+   for semantic ranking).
+2. **Warm Hit?** checks the best score against the configured threshold.
+3. **Green path (warm hit):** results flow to **Prompt Builder**, which injects
+   only the top-K rows into the system prompt before invoking the **LLM**.
+   The vector tier is never touched.
+4. **Orange path (warm miss):** the query falls through to **Long-Term Memory**
+   (LangGraph's `InMemoryStore` with an embedding index, `PostgresStore`, or
+   any `BaseStore`) and the LLM consumes those results as fallback.
+5. **Dashed write-back loop:** the LLM response is captured by the decorator
+   and written back to WarmMemory (and mirrored to Long-Term Memory by the
+   `memory_write` node), so future turns can recall it.
+
+On the synthetic benchmark, ~50% of turns take the green path, eliminating
+that many vector-store calls.
+
+The diagram ships in two paired formats:
+
+- **[`docs/warm_memory_architecture.drawio.svg`](docs/warm_memory_architecture.drawio.svg)** —
+  the rendered SVG that GitHub displays inline. The decision arrows flow
+  ("marching ants" SMIL animation) so the hot/cold paths read at a glance.
+  Open the file directly in a browser to see the animation; GitHub also
+  renders the animation when displaying the SVG.
+- **[`docs/warm_memory_architecture.drawio`](docs/warm_memory_architecture.drawio)** —
+  the editable mxgraph source. Open at [diagrams.net](https://app.diagrams.net)
+  (File → Open from device) to edit; re-export the SVG when done.
+
+The `.drawio.svg` also embeds the mxgraph XML in its `content` attribute, so
+either file round-trips through the editor — they're kept in sync from the
+same generator script.
+
+For a richer narrated walkthrough, open
+[`docs/warm_memory_guide.html`](docs/warm_memory_guide.html) locally or publish
+it with GitHub Pages.
 
 ## Development
 
@@ -213,10 +260,10 @@ python3 -m unittest discover -s tests -v
 ## LangGraph Integration
 
 WarmMemory ships an optional `warm_memory.langgraph` module that plugs directly
-into the LangGraph ecosystem. Install the extra:
+into the LangGraph ecosystem. Install with the extra:
 
 ```bash
-python3 -m pip install -e ".[langgraph]"
+pip install warm-memory[langgraph]
 ```
 
 ### Drop-in `BaseStore`
@@ -297,8 +344,9 @@ to compare against real semantic search.
 - record actual model latency and token usage from a live LLM pipeline
 - add charts and experiment summaries for publication-style reporting
 - TTL support for the LangGraph `BaseStore`
-- publish `warm-memory` to PyPI and propose inclusion in LangGraph's third-party
-  store list
+- ~~publish `warm-memory` to PyPI~~ ([live at v0.2.1](https://pypi.org/project/warm-memory/))
+- propose inclusion in LangGraph's third-party store list (LangChain Forum
+  proposal in flight)
 
 ## License