Metadata-Version: 2.4
Name: hebbrix
Version: 2.3.2
Summary: Advanced Memory API for AI Agents with Reinforcement Learning - 3-line integration
Author-email: Hebbrix Team <support@hebbrix.com>
Maintainer-email: Hebbrix Team <support@hebbrix.com>
License: MIT License
        
        Copyright (c) 2025 Hebbrix
        
        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.
        
Project-URL: Homepage, https://hebbrix.com
Project-URL: Documentation, https://docs.hebbrix.com
Project-URL: Repository, https://github.com/hebbrix/hebbrix-python
Project-URL: Bug Tracker, https://github.com/hebbrix/hebbrix-python/issues
Project-URL: API Reference, https://api.hebbrix.com/docs
Keywords: ai,memory,agents,llm,chatbot,assistant,ml,reinforcement-learning,knowledge-graph,vector-search,rag,temporal,procedural-memory,working-memory
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Database
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8<6.0.0,>=5.0.4; python_full_version < "3.8.1" and extra == "dev"
Requires-Dist: flake8>=6.0.0; python_full_version >= "3.8.1" and extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: cryptography>=42.0.0; extra == "dev"
Dynamic: license-file

# Hebbrix Python SDK

[![PyPI version](https://img.shields.io/pypi/v/hebbrix.svg)](https://pypi.org/project/hebbrix/)
[![Python versions](https://img.shields.io/pypi/pyversions/hebbrix.svg)](https://pypi.org/project/hebbrix/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Official Python SDK for the Hebbrix api - **the only memory API with Reinforcement Learning**.

## 🚀 Features

- ✅ **Core API Coverage** - Typed resources for memories, search, and ProofLoop
- ✅ **Reinforcement Learning** - Train AI agents to optimize memory operations
- ✅ **Temporal Knowledge Graphs** - Track facts over time with bi-temporal model
- ✅ **Procedural Memory** - Store and execute learned skills
- ✅ **Working Memory** - Short-term context buffer for conversations
- ✅ **Memory Consolidation** - Automatic compression of episodic memories
- ✅ **ProofLoop** - Learn from outcomes with automatic, verifiable evidence receipts
- ✅ **Sync + Async** - Equivalent core memory and ProofLoop workflows
- ✅ **Type Hints** - Complete type annotations
- ✅ **Clean API** - Pythonic, intuitive interface

## 📦 Installation

```bash
pip install hebbrix
```

## 🔥 Quick Start

```python
import asyncio
from hebbrix import MemoryClient

async def main():
    # Initialize client
    client = MemoryClient(api_key="mem_sk_your_api_key")

    # Create a collection
    collection = await client.collections.create(
        name="My AI Agent",
        description="Personal memory for my chatbot"
    )

    # Store a memory
    memory = await client.memories.create(
        collection_id=collection["id"],
        user_id="customer-7",
        agent_id="support-agent",
        content="User prefers dark mode and loves Python",
        importance=0.9,
        wait_for_index=True,
    )

    # wait_for_index=True polls the returned memory status through the SDK.
    # It returns only when searchable=true, raises on terminal failure, and
    # raises TimeoutError if the caller's readiness deadline expires.

    # Batch contract: a successful synchronous return means every accepted item
    # is searchable. A bounded server timeout raises explicitly and is safe to
    # retry with the same idempotency key; it is never a successful 202.
    batch = await client.memories.create_batch(
        [{"content": "First fact"}, {"content": "Second fact"}],
        collection_id=collection["id"],
        wait_for_index=True,
        idempotency_key="import-42",
    )
    # For wait_for_index=False receipts:
    # batch = await client.memories.wait_batch_until_searchable(batch)

    # Search memories
    results = await client.search(
        query="What programming language does user like?",
        collection_id=collection["id"],
        limit=5
    )

    print(results)

    # Close client
    await client.close()

asyncio.run(main())
```

Blocking applications can use the same create/search/ProofLoop fields:

```python
from hebbrix import SyncMemoryClient

with SyncMemoryClient(api_key="mem_sk_your_api_key") as client:
    collection = client.collections.create(name="My Agent")
    client.memories.create(
        collection_id=collection["id"],
        user_id="customer-7",
        content="User prefers concise answers",
        wait_for_index=True,
    )
    results = client.search(
        "How should answers be formatted?",
        collection_id=collection["id"],
        user_id="customer-7",
    )
```

## ProofLoop: search → decision → outcome → proof

```python
search = await client.search_with_proof(
    "What should the agent do next?",
    collection_id="collection-42",
    user_id="customer-7",
)
decision = await client.proofloop.decide(
    policy_key="agent.next_action",
    candidates=[{"action_key": "act"}, {"action_key": "ask"}],
    collection_id="collection-42",
    user_id="customer-7",
    proof_context=search["proof_context"],
)
await client.proofloop.record_outcome(
    decision["decision_id"], success=True, idempotency_key="run-123-result"
)
proof = await client.proofloop.proof(decision["decision_id"])
```

## 📚 Complete Documentation

Visit https://docs.hebbrix.com for full documentation.

## 🔗 Links

- **Documentation**: https://docs.hebbrix.com
- **API Reference**: https://api.hebbrix.com/docs
- **GitHub**: https://github.com/hebbrix/hebbrix
- **Examples**: https://github.com/hebbrix/examples

## 📄 License

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

---

**Built with ❤️ by the Hebbrix team**
