> ## Documentation Index
> Fetch the complete documentation index at: https://mneno.lollopanta.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Architecture

> Integrate Mneno with external AI services like embeddings and rerankers.

Mneno is provider-agnostic. While the core runtime is deterministic and local by default, you can easily integrate external services to enhance retrieval and context building.

## Supported Providers

Mneno currently supports three types of providers via standard protocols:

* **EmbeddingProvider**: Used for semantic search and relevance scoring.
* **RerankerProvider**: Used for second-stage ranking of search results.
* **LLMProvider**: Used for validated memory extraction and optional wording improvements for deterministic compaction merges.

## Integrating an Embedding Provider

To enable semantic search, pass an `EmbeddingProvider` to the `MemoryClient`.

```python theme={null}
from mneno import MemoryClient
from mneno.providers.embedding import DummyEmbeddingProvider

# Using the built-in dummy provider for local testing
client = MemoryClient(
    embedding_provider=DummyEmbeddingProvider(dimensions=1536)
)

# Search with semantic relevance enabled
results = client.search("AI memory SDK", use_semantic=True)
```

### Implementing a Custom Provider

You can integrate any service by implementing the `EmbeddingProvider` protocol in an optional integration package or application layer.

```python theme={null}
class MyOpenAIProvider:
    name = "openai"

    def embed(self, texts: list[str]) -> list[list[float]]:
        # Call OpenAI API and return embeddings
        pass

client = MemoryClient(embedding_provider=MyOpenAIProvider())
```

## Integrating a Reranker Provider

Rerankers are used to re-order candidate memories after the initial scoring phase.

```python theme={null}
from mneno.providers.reranker import DummyRerankerProvider

client = MemoryClient(
    reranker_provider=DummyRerankerProvider()
)

# Search with reranking enabled
results = client.search("What is the user building?", use_reranker=True)

for result in results:
    print(f"Original Rank: {result.original_rank}")
    print(f"Reranked Rank: {result.reranked_rank}")
    print(f"Reason: {result.rerank_reason}")
```

## Provider Registry

Mneno includes a `ProviderRegistry` to help you manage and swap providers dynamically.

```python theme={null}
from mneno.providers import ProviderRegistry

registry = ProviderRegistry()
registry.register_embedding("openai", MyOpenAIProvider())

provider = registry.get_embedding("openai")
```

## Why Protocols?

By using protocols instead of direct dependencies:

* **Zero Core Bloat**: Mneno doesn't force you to install large SDKs like `openai` or `cohere`.
* **Future Proof**: You can swap providers as better models become available without changing your core memory logic.
* **Testability**: Use dummy providers for fast, deterministic local tests.

Real provider SDKs, credentials, and network calls remain outside the core package.