evolink-sdk

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

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.

pip install evolink-sdk

Configure the API endpoint and workspace API key:

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

Then ingest content and query it:

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:

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:

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:

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.

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:

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:

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:

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:

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:

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:

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:

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:

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

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 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