Metadata-Version: 2.5
Name: evolink-sdk
Version: 0.1.2
Summary: Async Python SDK for the Evolink memory and RAG API
Project-URL: Documentation, https://github.com/sireto/evolink/blob/master/sdk/README.md
Project-URL: Repository, https://github.com/sireto/evolink
Author: Evolink
License: MIT
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Description-Content-Type: text/markdown

# evolink-sdk

Python client for **Evolink** — a memory and retrieval platform for document
ingestion, durable memory extraction, profiles, embeddings, reranking, and RAG.

[![PyPI](https://img.shields.io/pypi/v/evolink-sdk)](https://pypi.org/project/evolink-sdk/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit/)

The SDK is a lightweight **async HTTP client** for a deployed Evolink API.
Processing stays server-side: document parsing and chunking, memory extraction
and reconciliation, embeddings, reranking, profiles, model execution, and
storage are managed by Evolink rather than bundled into the client.

```sh
pip install evolink-sdk
```

Configure the API endpoint and workspace API key:

```sh
export EVOLINK_API_URL="https://sdk.evolink.example.com/api/v1"
export EVOLINK_API_KEY="sk_…"
```

Then ingest content and query it:

```python
from evolink_sdk import EvolinkClient

async with EvolinkClient.from_env() as client:
    document = await client.add(
        content="The platform team standardizes on PostgreSQL.",
        name="team-preferences.md",
        task_type="memory",
    )

    result = await client.rag.query(
        query="What database does the platform team use?",
        document_id=document["id"],
    )

    print(result["answer"])
```

`EVOLINK_API_KEY` is the workspace credential generated from the Evolink admin
dashboard. Store it as a server-side secret and never expose it in browser code.

Document ingestion supports two processing modes:

```python
await client.add(content="…", task_type="memory")    # default
await client.add(content="…", task_type="superrag")
```

`memory` processes the document for retrieval and extracts durable atomic
memories, reconciles them with existing knowledge, creates relationships,
and updates profiles.

`superrag` processes and indexes the document for retrieval without creating
durable memories.

Memory processing can also control whether existing knowledge participates
in reconciliation:

```python
await client.add(
    content="The team now standardizes on PostgreSQL.",
    task_type="memory",
    dreaming="dynamic",      # use related existing memories
    batch_size=5,
)
```

`dreaming="dynamic"` is the default and uses related workspace memories during
reconciliation. `dreaming="instant"` processes the document independently.
`batch_size` controls how many document chunks are supplied to each memory
extraction call and defaults to `5`.

The client exposes the same Evolink capabilities through dedicated namespaces:

```python
client.documents     # ingestion and document lifecycle
client.memories      # durable memories and stateless extraction
client.profiles      # generated knowledge profiles
client.embeddings    # stateless embedding generation
client.reranking     # stateless context reranking
client.rag           # retrieval and answer generation
client.config()      # safe server configuration
```

### Documents

Create documents from text or URLs, upload files, inspect processing results,
retry failures, and retrieve generated chunks, memories, and usage.

```python
document = await client.documents.create(
    name="architecture.md",
    content="The platform uses PostgreSQL for transactional workloads.",
    task_type="memory",
)

uploaded = await client.documents.upload_file(
    file="./handbook.pdf",
    content_type="application/pdf",
    task_type="superrag",
)

details = await client.documents.get(document["id"])
chunks = await client.documents.chunks(document["id"])
memories = await client.documents.memories(document["id"])
usage = await client.documents.usage(document["id"])
```

### Memories

Create and manage durable workspace memories:

```python
memory = await client.memories.add(
    content="The user prefers PostgreSQL.",
    memory_type="preference",
    importance=0.85,
)

results = await client.memories.search(content="database preference")
```

Memory types are `semantic`, `episodic`, and `preference`.

Memory extraction is also available as a **stateless** operation:

```python
drafts = await client.memories.generate(
    content="The user prefers PostgreSQL and attended PyCon last month.",
    existing_memories=["The user uses MySQL."],
)
```

`memories.generate()` returns extracted memory drafts and relationship hints
without creating or modifying persisted memories.

### Profiles

Profiles provide a projection of the knowledge extracted from workspace or
document memories:

```python
workspace_profile = await client.profiles.get()

document_profile = await client.profiles.get(
    document_id=document["id"],
)

await client.profiles.refresh()
```

Profiles can also be generated statelessly from supplied content:

```python
result = await client.profiles.generate(
    workspace_id="workspace-123",
    document_id=document["id"],
    content="The team prefers PostgreSQL.",
)
```

Stateless profile generation does not persist memories, profiles, or
relationships.

### Embeddings

Generate embeddings using the server-configured provider without storing the
input or resulting vectors:

```python
embeddings = await client.embeddings.generate(
    texts=[
        "The team prefers PostgreSQL.",
        "Redis is used for caching.",
    ],
    input_type="document",
)
```

### Reranking

Rerank caller-provided contexts using the configured server-side reranker:

```python
ranked = await client.reranking.rerank(
    query="Which database does the team prefer?",
    contexts=[
        {"id": "redis", "content": "The team uses Redis for caching."},
        {"id": "postgres", "content": "The team prefers PostgreSQL."},
    ],
    top_k=1,
)
```

Reranking only scores the supplied contexts. It does not perform retrieval or
persist the results.

### RAG

Evolink retrieval can search extracted memories, original document chunks, or
both:

```python
evidence = await client.rag.retrieve(
    query="Which database does the platform team use?",
    search_mode="hybrid",
    limit=20,
    rerank=True,
    rerank_limit=8,
    rewrite_query=True,
)
```

The supported search modes are:

* `memory` — search extracted durable memories.
* `document` — search original document chunks.
* `hybrid` — search both sources; this is the default.

Generate an answer directly from retrieved evidence:

```python
result = await client.rag.query(
    query="What is the team's database standard and why?",
    search_mode="hybrid",
    top_k=12,
    rephrasing_enabled=True,
    rerank=True,
    rerank_top_k=6,
)

print(result["answer"])
print(result["sources"])
```

`await client.rag.history()` exposes stored RAG queries together with their answers,
sources, retrieved chunks, scores, and rewritten queries when applicable.

### Server configuration

```python
config = await client.config()
```

`client.config()` exposes safe workspace configuration such as enabled
providers and model names. Provider credentials and other secrets are never
returned.

Available capabilities depend on the connected Evolink deployment. Memory
extraction and answer generation require a configured language model,
semantic retrieval requires embeddings, and reranking requires a configured
reranker.

The SDK itself does not require database credentials, provider API keys,
Torch, local models, or provider-specific SDKs. See
the complete [SDK integration guide](https://github.com/sireto/evolink/blob/master/docs/SDK.md) for method and parameter details.

The SDK intentionally does not provision workspaces, generate API keys,
manage admin settings, expose provider credentials, or provide dashboard and
graph administration. Those responsibilities belong to the Evolink
deployment and admin API.

## Errors

API failures raise `EvolinkError` with `status_code`, `message`, and the
original response `payload`.

Common statuses are `400` for invalid parameters, `401` for an invalid or
revoked API key, `404` for unknown resources, and `422` for schema validation
errors.

All SDK operations are asynchronous. UUID parameters accept both strings and
`uuid.UUID` values.

## License

MIT
