Metadata-Version: 2.4
Name: substrate-haystack
Version: 0.1.1
Summary: SUBSTRATE memory components for Haystack -- causal memory, emotion, and identity retrieval and storage.
Project-URL: Homepage, https://garmolabs.com/substrate.html
Project-URL: Documentation, https://github.com/PKaldone/substrate-mcp
Project-URL: Repository, https://github.com/PKaldone/substrate-mcp
Project-URL: Issues, https://garmolabs.com/substrate.html
Author-email: Garmo Labs <hello@garmolabs.com>
License-Expression: MIT
Keywords: ai,causal-memory,emotional-state,garmo-labs,haystack,mcp,memory,retriever,substrate
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: haystack-ai>=2.0
Requires-Dist: httpx>=0.25
Description-Content-Type: text/markdown

# substrate-haystack

SUBSTRATE memory components for [Haystack](https://haystack.deepset.ai/) pipelines. Retriever and writer that connect Haystack to [SUBSTRATE](https://garmolabs.com/substrate.html)'s causal memory, emotional state, and identity continuity.

## What SUBSTRATE adds to Haystack

- **Causal memory retrieval** -- episodes linked by cause-effect rules, not just vector similarity
- **Emotional context output** -- retriever exposes the entity's emotional state alongside documents
- **Persistent storage** -- writer stores documents through the entity's full cognitive pipeline
- **Hybrid search** -- semantic + keyword retrieval across the entity's full knowledge store
- **Identity continuity** -- cryptographically verified entity state persists across sessions

## Installation

```bash
pip install substrate-haystack
```

## Quick start: Retrieval pipeline

```python
import os
from haystack import Pipeline
from haystack.components.generators import OpenAIGenerator
from haystack.components.builders import PromptBuilder
from substrate_haystack import SubstrateMemoryRetriever

retriever = SubstrateMemoryRetriever(
    api_key=os.environ["SUBSTRATE_API_KEY"],
)

prompt_builder = PromptBuilder(
    template="""
    Context from SUBSTRATE memory:
    {% for doc in documents %}
    - {{ doc.content }}
    {% endfor %}

    Entity emotional state: {{ entity_state }}

    Question: {{ query }}
    Answer:
    """
)

generator = OpenAIGenerator(model="gpt-4o")

pipe = Pipeline()
pipe.add_component("retriever", retriever)
pipe.add_component("prompt_builder", prompt_builder)
pipe.add_component("llm", generator)

pipe.connect("retriever.documents", "prompt_builder.documents")
pipe.connect("retriever.entity_state", "prompt_builder.entity_state")
pipe.connect("prompt_builder", "llm")

result = pipe.run({
    "retriever": {"query": "What patterns have we identified?"},
    "prompt_builder": {"query": "What patterns have we identified?"},
})

print(result["llm"]["replies"][0])
```

## Quick start: Writing to memory

```python
from haystack import Document, Pipeline
from substrate_haystack import SubstrateMemoryWriter

writer = SubstrateMemoryWriter(
    api_key=os.environ["SUBSTRATE_API_KEY"],
)

pipe = Pipeline()
pipe.add_component("writer", writer)

result = pipe.run({
    "writer": {
        "documents": [
            Document(content="The team decided to use event sourcing for the audit trail."),
            Document(content="Performance testing showed 99th percentile at 45ms."),
        ]
    }
})

print(f"Stored {result['writer']['documents_written']} documents")
```

## Components

### SubstrateMemoryRetriever

Retrieves documents from SUBSTRATE memory using hybrid search.

**Inputs:**
| Name    | Type  | Description                          |
|---------|-------|--------------------------------------|
| `query` | `str` | Search query string                  |
| `top_k` | `int` | Maximum results to return (default 5)|

**Outputs:**
| Name           | Type             | Description                              |
|----------------|------------------|------------------------------------------|
| `documents`    | `list[Document]` | Retrieved documents from SUBSTRATE memory|
| `entity_state` | `dict`           | Entity emotional state (UASV dimensions) |

**Parameters:**
| Parameter         | Default                                           | Description                         |
|-------------------|---------------------------------------------------|-------------------------------------|
| `api_key`         | `$SUBSTRATE_API_KEY`                               | Your SUBSTRATE API key              |
| `base_url`        | `https://substrate.garmolabs.com/mcp-server/mcp`  | MCP server endpoint                 |
| `timeout`         | `30.0`                                             | HTTP request timeout (seconds)      |
| `include_emotion` | `True`                                             | Fetch emotional context with results|

### SubstrateMemoryWriter

Stores documents into SUBSTRATE memory via the `respond` tool.

**Inputs:**
| Name        | Type             | Description                  |
|-------------|------------------|------------------------------|
| `documents` | `list[Document]` | Documents to store in memory |

**Outputs:**
| Name                | Type         | Description                            |
|---------------------|--------------|----------------------------------------|
| `documents_written` | `int`        | Number of documents successfully stored|
| `responses`         | `list[str]`  | Entity responses for each document     |

## API key

Get your API key at [garmolabs.com](https://garmolabs.com). The free tier includes `memory_search` and `get_emotion_state`. Upgrade to Pro for `hybrid_search` and `get_trust_state`.

## License

MIT -- see [LICENSE](LICENSE) for details.

Built by [Garmo Labs](https://garmolabs.com).
