# Chat
Source: https://docs.useskald.com/docs/api-reference/chat

API reference for the chat /api/v1/chat endpoint

## Chat API

Ask questions about your knowledge base using an AI agent with optional filtering to focus the search context.

### POST /api/v1/chat

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Request (using Project API Key):**

```json theme={null}
{
    "query": "What were the main points discussed in the Q1 meeting?",
    "stream": false,
    "system_prompt": "You are a helpful assistant that can answer questions about the memo.",
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "meeting-notes",
            "filter_type": "native_field"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["q1", "meeting"],
            "filter_type": "native_field"
        }
    ]
}
```

**Request (using Token Authentication):**

```json theme={null}
{
    "query": "What were the main points discussed in the Q1 meeting?",
    "project_id": "project-uuid",
    "stream": false,
    "filters": [
        {
            "field": "category",
            "operator": "eq",
            "value": "meeting",
            "filter_type": "custom_metadata"
        }
    ]
}
```

**Parameters:**

* `query` (string, required): The question to ask
* `project_id` (UUID, optional): **Only required when using Token Authentication**
* `stream` (boolean, optional): Enable streaming responses (default: false)
* `system_prompt` (string, optional): A system prompt to guide the chat agent's behavior
* `filters` (array of filter objects, optional): Filters to narrow the search context. See [Filters](/docs/api-reference/filters) for detailed documentation.

**Filter Support:**

Filters are applied during the initial retrieval of relevant context, allowing you to:

* Filter by a "workspace" or "team" ID from your side
* Focus the chat on specific sources (e.g., only Notion docs)
* Query only memos with certain tags
* Exclude certain categories of content

See [Filters](/docs/api-reference/filters) for complete documentation on filter structure, operators, and examples.

**Response (Non-streaming):**

```json theme={null}
{
    "ok": true,
    "response": "The main points discussed in the Q1 meeting were:\n1. Revenue targets \n2. Hiring plans \n3. Product roadmap",
    "intermediate_steps": []
}
```

**Response (Streaming):**

When `stream: true`, returns Server-Sent Events:

```
Content-Type: text/event-stream

: ping

data: {"type": "token", "content": "The"}

data: {"type": "token", "content": " main"}

data: {"type": "done"}
```

### GET /api/v1/chat

Get a list of chats.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Query Parameters:**

* `page` (integer, optional): Page number (default: 1)
* `page_size` (integer, optional): Page size (default: 20)

**Example Response:**

```json theme={null}
{
    "results": [
        {
            "uuid": "84365e7e-381e-47da-9104-8dcc7a83920e",
            "created_at": "2025-12-13T16:57:45.240Z",
            "title": "What does undefined do?",
            "message_count": 2,
            "last_message_at": "2025-12-13T16:57:45.242Z"
        }
    ],
    "count": 1,
    "page": 1,
    "page_size": 1,
    "total_pages": 1
}
```

* Count: The total number of chats
* Page: The page number
* Page size: The number of chats per page
* Total pages: The total number of pages

### GET /api/v1/chat/:chat\_uuid

Get a chat by its UUID.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Path Parameters:**

* `:chat_uuid` (string, required): The UUID of the chat

**Example Response:**

```json theme={null}
{
    "uuid": "4a71fd8b-2ca0-42d8-9bfd-8d11d080ecf3",
    "created_at": "2025-11-22T01:13:41.113Z",
    "messages": [
        {
            "uuid": "e03af6a7-da4d-4508-9057-4dcc25eec7e0",
            "content": "what's 2+2?",
            "sent_by": "user",
            "sent_at": "2025-11-22T01:13:41.114Z",
            "client_system_prompt": null
        },
        {
            "uuid": "d72c88d0-c6d4-4155-8601-c695abac5cab",
            "content": "2+2 is 4",
            "sent_by": "model",
            "sent_at": "2025-11-22T01:13:41.115Z",
            "client_system_prompt": null
        }
    ]
}
```

### Error Responses

**Missing query (400):**

```json theme={null}
{
    "error": "Query is required"
}
```

**Invalid filters (400):**

```json theme={null}
{
    "error": "Filters must be a list"
}
```

**Invalid filter structure (400):**

```json theme={null}
{
    "error": "Invalid filter: <specific error message>"
}
```

**Agent error (500):**

```json theme={null}
{
    "error": "Agent error: <error details>"
}
```


# Filters
Source: https://docs.useskald.com/docs/api-reference/filters

Advanced filtering for search, chat, and generate endpoints

## Overview

Filters allow you to narrow down results and context in the `/api/v1/search`, `/api/v1/chat`, and `/api/v1/generate` endpoints. You can filter by native memo fields or custom metadata fields using various operators.

Filters are applied using AND logic - all filters must match for a memo to be included.

## Filter Structure

Each filter object has the following structure:

```json theme={null}
{
    "field": "field_name",
    "operator": "operator_name",
    "value": "value or [array]",
    "filter_type": "native_field | custom_metadata"
}
```

**Required Fields:**

* `field` (string): The field name to filter on
* `operator` (string): The comparison operator to use
* `value` (string | array): The value to compare against (arrays required for `in` and `not_in`)
* `filter_type` (string): Either `native_field` or `custom_metadata`

## Filter Types

### Native Fields

Filter on built-in memo properties using `filter_type: "native_field"`:

* `title` - Memo title
* `source` - Source system name
* `client_reference_id` - External reference ID
* `tags` - Memo tags (must use `in` or `not_in` operator with array value)

**Example:**

```json theme={null}
{
    "field": "source",
    "operator": "eq",
    "value": "notion",
    "filter_type": "native_field"
}
```

### Custom Metadata

Filter on any field from a memo's `metadata` JSON object using `filter_type: "custom_metadata"`:

**Example:**

```json theme={null}
{
    "field": "category",
    "operator": "contains",
    "value": "tutorial",
    "filter_type": "custom_metadata"
}
```

This filters memos where `metadata.category` contains "tutorial".

## Operators

### Equality Operators

* `eq` - Equals (exact match)
* `neq` - Not equals

**Example:**

```json theme={null}
{
    "field": "source",
    "operator": "eq",
    "value": "confluence",
    "filter_type": "native_field"
}
```

### String Operators

* `contains` - Contains substring (case-insensitive)
* `startswith` - Starts with (case-sensitive)
* `endswith` - Ends with (case-sensitive)

**Example:**

```json theme={null}
{
    "field": "title",
    "operator": "contains",
    "value": "meeting",
    "filter_type": "native_field"
}
```

### Array Operators

* `in` - Value is in array (requires array value)
* `not_in` - Value is not in array (requires array value)

**Example:**

```json theme={null}
{
    "field": "source",
    "operator": "in",
    "value": ["notion", "confluence", "docs"],
    "filter_type": "native_field"
}
```

**Tags Example (always requires array):**

```json theme={null}
{
    "field": "tags",
    "operator": "in",
    "value": ["meeting", "q1"],
    "filter_type": "native_field"
}
```

## Combining Filters

Multiple filters use AND logic - all filters must match for a memo to be included in results.

**Example:**

```json theme={null}
{
    "query": "python tutorial",
    "search_method": "chunk_vector_search",
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "docs.python.org",
            "filter_type": "native_field"
        },
        {
            "field": "level",
            "operator": "eq",
            "value": "beginner",
            "filter_type": "custom_metadata"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["tutorial"],
            "filter_type": "native_field"
        }
    ]
}
```

This returns only memos where:

* Title/content matches "python tutorial" AND
* Source equals "docs.python.org" AND
* Metadata field "level" equals "beginner" AND
* Has at least one tag in \["tutorial"]

## Common Filter Patterns

### Filter by Source

Limit results to specific source systems:

```json theme={null}
{
    "field": "source",
    "operator": "in",
    "value": ["notion", "confluence"],
    "filter_type": "native_field"
}
```

### Filter by Tags

Include memos with specific tags:

```json theme={null}
{
    "field": "tags",
    "operator": "in",
    "value": ["meeting", "important"],
    "filter_type": "native_field"
}
```

Exclude memos with specific tags:

```json theme={null}
{
    "field": "tags",
    "operator": "not_in",
    "value": ["archived", "draft"],
    "filter_type": "native_field"
}
```

### Filter by Custom Metadata

Filter by any custom metadata field:

```json theme={null}
{
    "field": "department",
    "operator": "eq",
    "value": "engineering",
    "filter_type": "custom_metadata"
}
```

### Partial String Match

Find memos with titles containing specific text:

```json theme={null}
{
    "field": "title",
    "operator": "contains",
    "value": "roadmap",
    "filter_type": "native_field"
}
```

### Multiple Conditions

Combine filters for precise results:

```json theme={null}
{
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "product-docs",
            "filter_type": "native_field"
        },
        {
            "field": "status",
            "operator": "eq",
            "value": "published",
            "filter_type": "custom_metadata"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["feature", "specification"],
            "filter_type": "native_field"
        }
    ]
}
```

## Error Responses

**Invalid filter structure (400):**

```json theme={null}
{
    "error": "Invalid filter: <specific error message>"
}
```

**Common filter errors:**

* Missing required fields (`field`, `operator`, `value`, `filter_type`)
* Invalid operator (must be one of: `eq`, `neq`, `contains`, `startswith`, `endswith`, `in`, `not_in`)
* Invalid filter\_type (must be `native_field` or `custom_metadata`)
* Invalid native field (must be `title`, `source`, `client_reference_id`, or `tags`)
* Tags filter must use `in` or `not_in` operator with array value
* `in` and `not_in` operators require array value

## Using Filters Across Endpoints

### Search Endpoint

Filters narrow down search results:

```json theme={null}
POST /api/v1/search
{
    "query": "api documentation",
    "search_method": "chunk_vector_search",
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "technical-docs",
            "filter_type": "native_field"
        }
    ]
}
```

See [Search API](/docs/api-reference/search) for details.

### Chat Endpoint

Filters control which memos are used as context for chat responses:

```json theme={null}
POST /api/v1/chat
{
    "query": "What are our Q1 goals?",
    "filters": [
        {
            "field": "tags",
            "operator": "in",
            "value": ["q1", "goals"],
            "filter_type": "native_field"
        }
    ]
}
```

See [Chat API](/docs/api-reference/chat) for details.

### Generate Endpoint

Filters determine which memos provide context for document generation:

```json theme={null}
POST /api/v1/generate
{
    "prompt": "Create a technical overview document",
    "filters": [
        {
            "field": "document_type",
            "operator": "eq",
            "value": "specification",
            "filter_type": "custom_metadata"
        }
    ]
}
```

See [Generate API](/docs/api-reference/generate-doc) for details.

## Tips and Best Practices

1. **Use specific filters** - Narrow your scope to improve relevance and reduce noise
2. **Combine native and custom fields** - Mix source/tags filters with metadata filters for precision
3. **Test filters incrementally** - Add filters one at a time to understand their impact
4. **Empty filters array** - Equivalent to no filters, searches entire project
5. **Case sensitivity** - `contains` is case-insensitive, but `startswith` and `endswith` are case-sensitive
6. **Tags always use arrays** - Even for single tag, use `["tag"]` format with `in` or `not_in`


# Introduction
Source: https://docs.useskald.com/docs/api-reference/introduction

Understand general concepts and response codes

### Base URL

The Skald API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy. The API does not support HTTP.
All requests contain the following base URL:

```javascript theme={null}
https://api.useskald.com
```

### Authentication

Each Project inside an Organization on Skald have it's own API key.
It follows the format: **sk\_proj\_xxxxxxxxxxxxxxxxxxxxxxx**

To authenticate you need to add an Authorization header with the contents of the header being Bearer sk\_proj\_xxxxxxxxx where sk\_proj\_xxxxxxxxx is your project API Key.

```javascript theme={null}
Authorization: Bearer sk_proj_xxxxxxxxx
```

### Response codes

Skald uses standard HTTP codes to indicate the success or failure of your requests.
In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.

| Status | Description                             |
| ------ | --------------------------------------- |
| 200    | Successful request.                     |
| 400    | Check that the parameters were correct. |
| 401    | The API key used was missing.           |
| 403    | The API key used was invalid.           |
| 404    | The resource was not found.             |
| 429    | The rate limit was exceeded.            |


# Memos
Source: https://docs.useskald.com/docs/api-reference/memos

API reference for the POST /api/v1/memo endpoint

## Memos API

Manage your memos, including creating, updating, deleting, and retrieving them.

### POST /api/v1/memo

Create a new memo. The memo will be automatically processed (summarized, chunked, and indexed for search).

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Request:**

```json theme={null}
{
    "title": "Meeting Notes",
    "content": "Full content of the memo...",
    "metadata": {
        "type": "notes",
        "author": "John Doe"
    },
    "reference_id": "external-id-123",
    "tags": ["meeting", "q1"],
    "source": "notion",
    "expiration_date": "2024-12-31T23:59:59Z"
}
```

**Required Fields:**

* `title` (string, max 255 chars)
* `content` (string)

**Optional Fields:**

* `metadata` (object): Custom JSON metadata
* `reference_id` (string, max 255 chars): External reference ID
* `tags` (array of strings): Tags for categorization
* `source` (string, max 255 chars): Source system name
* `expiration_date` (datetime): When the memo should expire

**Response:**

```json theme={null}
{
    "ok": true
}
```

### GET /api/v1/memo/

Get memo details by UUID or client reference ID.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Query Parameters:**

* `id_type` (string, optional): Type of identifier used. Must be either:
  * `memo_uuid` (default) - Use memo UUID
  * `reference_id` - Use client\_reference\_id

**Examples:**

Get by UUID (default):

```
GET /api/v1/memo/550e8400-e29b-41d4-a716-446655440000
```

Get by client reference ID:

```
GET /api/v1/memo/external-id-123?id_type=reference_id
```

**Response:**

```json theme={null}
{
    "uuid": "memo-uuid",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "title": "Meeting Notes",
    "content": "Full content of the memo...",
    "summary": "Discussion about Q1 goals",
    "content_length": 1234,
    "metadata": { "type": "notes" },
    "client_reference_id": "external-id-123",
    "source": "notion",
    "type": "document",
    "expiration_date": "2024-12-31T23:59:59Z",
    "archived": false,
    "pending": false,
    "tags": [
        {
            "uuid": "tag-uuid",
            "tag": "meeting"
        }
    ],
    "chunks": [
        {
            "uuid": "chunk-uuid",
            "chunk_content": "First chunk content...",
            "chunk_index": 0
        }
    ]
}
```

**Error Responses:**

Invalid id\_type (400):

```json theme={null}
{
    "error": "id_type must be either 'memo_uuid' or 'reference_id'"
}
```

Memo not found (404):

```json theme={null}
{
    "error": "Memo not found"
}
```

### PATCH /api/v1/memo/

Partially update an existing memo by UUID or client reference ID. If the content is updated, all related data (summary, tags, chunks) will be deleted and the memo will be reprocessed.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Query Parameters:**

* `id_type` (string, optional): Type of identifier used. Must be either:
  * `memo_uuid` (default) - Use memo UUID
  * `reference_id` - Use client\_reference\_id

**Examples:**

Update by UUID (default):

```
PATCH /api/v1/memo/550e8400-e29b-41d4-a716-446655440000
```

Update by client reference ID:

```
PATCH /api/v1/memo/external-id-123?id_type=reference_id
```

**Request:**

```json theme={null}
{
    "title": "Updated Title",
    "metadata": { "type": "updated" },
    "client_reference_id": "new-ref-id",
    "source": "updated-source",
    "expiration_date": "2025-12-31T23:59:59Z",
    "content": "Updated content..."
}
```

**All Fields Optional:**

* `title` (string, max 255 chars): Update the memo title
* `metadata` (object): Update custom JSON metadata
* `client_reference_id` (string, max 255 chars): Update external reference ID
* `source` (string, max 255 chars): Update source system name
* `expiration_date` (datetime): Update expiration date
* `content` (string): Update the memo content (triggers reprocessing)

**Response:**

```json theme={null}
{
    "ok": true
}
```

**Notes:**

* When `content` is updated, the memo is automatically reprocessed (summary, tags, and chunks are regenerated)
* When other fields are updated without `content`, related data is preserved

**Error Responses:**

Invalid id\_type (400):

```json theme={null}
{
    "error": "id_type must be either 'memo_uuid' or 'reference_id'"
}
```

Memo not found (404):

```json theme={null}
{
    "error": "Memo not found"
}
```

Access denied (403):

```json theme={null}
{
    "error": "Resource does not belong to the project"
}
```

or

```json theme={null}
{
    "error": "Access denied"
}
```

### DELETE /api/v1/memo/

Delete a memo by UUID or client reference ID and all its associated data (content, summary, tags, chunks).

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Query Parameters:**

* `id_type` (string, optional): Type of identifier used. Must be either:
  * `memo_uuid` (default) - Use memo UUID
  * `reference_id` - Use client\_reference\_id

**Examples:**

Delete by UUID (default):

```
DELETE /api/v1/memo/550e8400-e29b-41d4-a716-446655440000
```

Delete by client reference ID:

```
DELETE /api/v1/memo/external-id-123?id_type=reference_id
```

**Response:** `204 No Content`

**Error Responses:**

Invalid id\_type (400):

```json theme={null}
{
    "error": "id_type must be either 'memo_uuid' or 'reference_id'"
}
```

Memo not found (404):

```json theme={null}
{
    "error": "Memo not found"
}
```

Access denied (403):

```json theme={null}
{
    "error": "Resource does not belong to the project"
}
```

or

```json theme={null}
{
    "error": "Access denied"
}
```


# Search
Source: https://docs.useskald.com/docs/api-reference/search

API reference for the POST /api/v1/search endpoint

## Search API

### POST /api/v1/search

Search through memos using semantic search.

**Authentication:** Project API Key from [https://platform.useskald.com](https://platform.useskald.com)

**Request (using Project API Key):**

```json theme={null}
{
    "query": "quarterly goals",
    "limit": 10,
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "notion",
            "filter_type": "native_field"
        },
        {
            "field": "level",
            "operator": "eq",
            "value": "beginner",
            "filter_type": "custom_metadata"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["meeting", "q1"],
            "filter_type": "native_field"
        }
    ]
}
```

**Request (using Token Authentication):**

```json theme={null}
{
    "query": "quarterly goals",
    "project_id": "project-uuid",
    "limit": 10,
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "notion",
            "filter_type": "native_field"
        }
    ]
}
```

**Parameters:**

* `query` (string, required): The search query.
* `project_id` (UUID, optional): **Only required when using Token Authentication**.
* `limit` (integer, optional): Max results to return (1-50, default 10).
* `filters` (array of filter objects, optional): Array of filters to apply. See [Filters](/docs/api-reference/filters) for detailed documentation.

**Response:**

```json theme={null}
{
    "results": [
        {
            "memo_title": "Meeting Notes",
            "memo_uuid": "memo-uuid",
            "chunk_uuid": "chunk-uuid",
            "chunk_content": "Full content of the chunk...",
            "memo_summary": "Discussion about Q1 goals",
            "distance": 0.234
        }
    ]
}
```

**Notes:**

* `distance` is the vector similarity distance (lower is more similar).
* Empty filters array is equivalent to no filters.

**Error Responses:**

Missing query (400):

```json theme={null}
{
    "error": "Query is required"
}
```

Invalid search method (400):

```json theme={null}
{
    "error": "Search method is required and must be one of: title_contains, title_startswith, chunk_vector_search"
}
```

Limit too high (400):

```json theme={null}
{
    "error": "Limit must be less than or equal to 50"
}
```

Invalid filter (400):

```json theme={null}
{
    "error": "Invalid filter: <specific error message>"
}
```

See [Filters](/docs/api-reference/filters) for complete filter documentation and examples.


# Knowledge spaces and filters
Source: https://docs.useskald.com/docs/filtering

How to separate knowledge in Skald and filter information sources on retrieval

In Skald, you can create multiple projects to keep data segregated. This is useful when you use Skald for different applications, or when you have a staging and a prod environment, for example.

However, inside the same project, there are various use cases where you'd want to be able to filter what information sources are used for a given query, such as when you're using Skald to provide insights scoped to each one of your users.

In that case, you should use our filtering capabilities.

When creating a memo, there are various optional fields that you can provide that will be attached to the memo, such as `source`, `reference_id`, `tags`, and `metadata`.

All of these fields can then be used as filters when using our retrieval APIs, such that search results and chat responses will only query the memos that match the filters.

These fields (including all the metadata fields you provide) are indexed so not only will adding filters not affect retrieval performance, it will actually make it faster, by giving our system less context to process.

We recommend using `reference_id` to match a memo to an ID in your own system (e.g. a document ID) but other fields can be used for you to create knowledge spaces.

For instance, you can use `user_id:12345` as `source` or set `user_id = 12345` as a metadata field.

When filtering, you would then use a filter like this:

```json theme={null}
{
    "field": "source",
    "operator": "eq",
    "value": "user_id:12345",
    "filter_type": "native_field"
}
```

Or this:

```json theme={null}
{
    "field": "user_id",
    "operator": "eq",
    "value": "12345",
    "filter_type": "custom_metadata"
}
```

These filters will **ensure no context other than what matches the filter will be used to process query**.

If you have any questions or feedback about filtering, don't hesistate to reach out to `dev@useskald.com`.


# Introduction to Skald
Source: https://docs.useskald.com/docs/index

The API platform for building AI apps

## Overview

Skald is an open-source API platform for building AI apps, from internal tools and agents to public-facing apps.

We've seen a lot of companies spend hundreds of engineering hours and tens of thousands of dollars building RAGs that then don't perform well, which is why we built Skald.

Send context via our SDKs and get search and chat out-of-the-box, so you can get started in minutes.

Then configure your RAG engine to fit your exact needs, and evaluate its performance with our built-in evaluation tools.

**Node SDK example**

```js theme={null}
import { Skald } from '@skald-labs/skald-node';

const skald = new Skald('your-api-key-here');

await skald.createMemo({
  title: 'Meeting Notes',
  content: 'Full content of the memo...'
});

const chatRes = await skald.chat({
  query: 'What were the main points discussed in the Q1 meeting?'
});

console.log(chatRes.response);

```

## Getting started

To use Skald, you can start using our [Cloud version](https://platform.useskald.com/) for free (no credit card required) or [self-host it yourself](/docs/self-host/intro) (MIT license).

## Demo

<iframe title="Skald Demo" />

## Features

* **Chat:** Chat with your knowledge in Skald with just one API call
* **Search:** Use semantic search to find relevant context based on user queries
* **Turnkey configuration:** Get started in minutes with great defaults and then configure your RAG engine exactly how you want it.
* **Evaluate:** Evaluate the performance of your custom RAG engine with our built-in evaluation tools.
* **Powerful filtering:** Speed up and improve responses by filtering the accessible knowledge in every query.
* **Amazing DX, no bullsh\*t:** Implement in minutes with SDKs for every major language. Don't see yours? Open [an issue](https://github.com/skaldlabs/skald/issues/new) and we'll build it!
* **Truly open-source:** Our open source version is fully-featured, easy to deploy, and can even run with [no third-party dependencies](/docs/self-host/full-local).


# Memos
Source: https://docs.useskald.com/docs/memos

Understanding memos in Skald

Memos are the core unit of knowledge in Skald.

Memo comes from the Latin word *memorandum*, which means "something to be remembered".

Memos can be documents, notes, code, articles, or any other source of knowledge.

We've chosen to use a term that does not imply a specific format (like "page", or "document") exactly because memos can take any form you wish, as knowledge does.

So whenever you want to push knowledge to Skald, you create a memo. We then automatically extract extensive metadata from it, so that it can be easily searched for and used as context for AI agents.

Today, there are two ways to create memos in Skald:

1. Using plaintext
2. Uploading a document

On document uploads, we support PDFs, Word documents, PowerPoint presentations, and Excel spreadsheets.


# Skald CLI
Source: https://docs.useskald.com/docs/sdks/cli

Documentation on how to install and use the Skald CLI.

The Skald CLI is a command-line interface that allows users to manage memos, interact with a knowledge base, and generate documentation.

## Installation

To install the Skald CLI, run the following command:

```bash theme={null}
npm install -g @skald-labs/cli
```

Before using any other commands, authenticate with your API key:

```bash theme={null}
skald auth
```

## Usage

After installation, you can use the `skald` command:

```bash theme={null}
# Show help
skald --help

# Authenticate with your API key (first time setup)
skald auth

# Initialize documentation structure
skald docs init

# Add a memo from a file
skald memo add --title "Meeting Notes" --file-path ./notes.md

# Add a memo with tags
skald memo add -t "Project Update" -f ./update.md --tags "project,update"

# Write a memo using vi editor
skald memo write

# Write a memo with tags
skald memo write --tags "meeting,notes"

# Ask a question to your knowledge base
skald chat ask "What are our quarterly goals?"

# Ask about specific topics
skald chat ask "Tell me about the API authentication process"

# Show help for a specific command
skald docs --help

# Generate documentation (uses current directory by default)
skald docs generate

# Generate with custom paths
skald docs generate --config-path ./config --output-path ./dist/docs

# Using short flags
skald docs generate -c ./config -o ./dist/docs
```

## Commands

### Authentication

* `skald auth` - Authenticate with your project API key
  * Prompts for API key and stores it securely in `~/.skald/config` (macOS/Linux) or `%USERPROFILE%\.skald\config` (Windows)
  * **Required**: Must run this command before using any other commands

### Documentation Commands

* `skald docs init` - Initialize documentation structure with example outline.yml
  * `--config-path, -c <path>` - Path to configuration directory (defaults to current directory)
* `skald docs generate` - Generate documentation (requires authentication)
  * `--config-path, -c <path>` - Path to configuration file (defaults to current directory)
  * `--output-path, -o <path>` - Path to output directory (defaults to current directory)
  * **Required files**:
    * `<config-path>/.skald/outline.yml` - Outline configuration file (YAML format)
  * **Optional files**:
    * `<config-path>/.skald/rules.md` - Custom rules for documentation generation

### Memo Commands

* `skald memo add` - Add a new memo from a file (requires authentication)
  * `--title, -t <title>` - Title of the memo (required)
  * `--file-path, -f <path>` - Path to the file containing memo content (required)
  * `--tags <tags>` - Comma-separated tags for the memo
  * `--source <source>` - Source of the memo (defaults to "cli")
  * `--reference-id <id>` - External reference ID for the memo
* `skald memo write` - Write a new memo using vi editor (requires authentication)
  * `--tags <tags>` - Comma-separated tags for the memo
  * `--source <source>` - Source of the memo (defaults to "cli")
  * `--reference-id <id>` - External reference ID for the memo

### Chat Commands

* `skald chat ask <question>` - Ask a question to your knowledge base (requires authentication)
  * Streams the response in real-time to the console

## Expected Directory Structure for Documentation

When running `skald docs generate`, your project should have:

```
<config-path>/
└── .skald/
    ├── outline.yml     # Required: documentation outline (YAML format)
    └── rules.md        # Optional: custom generation rules
```

## YAML Outline Format

The `outline.yml` file uses the `_docs` key to define documentation files:

```yaml theme={null}
api:
  _docs:
    - name: authentication.md
      title: Authentication
      description: API authentication guide
  reference:
    _docs:
      - name: user.md
        title: User API
        description: User endpoints
features:
  _docs:
    - name: features.md
      title: Features Overview
```


# .NET SDK
Source: https://docs.useskald.com/docs/sdks/csharp

Documentation on how to use the Skald .NET SDK.

.NET/C# client library for the Skald API.

## Installation

```bash theme={null}
dotnet add package Skald
```

## Requirements

* .NET 8.0 or higher

## Usage

### Initialize the client

```csharp theme={null}
using Skald;

var client = new SkaldClient("your-api-key-here");
```

### Memo Management

#### Create a Memo

Create a new memo that will be automatically processed (summarized, tagged, chunked, and indexed for search):

```csharp theme={null}
var result = await client.CreateMemoAsync(new MemoData
{
    Title = "Meeting Notes",
    Content = "Full content of the memo...",
    Metadata = new Dictionary<string, object>
    {
        { "type", "notes" },
        { "author", "John Doe" }
    },
    ReferenceId = "external-id-123",
    Tags = new List<string> { "meeting", "q1" },
    Source = "notion",
    ExpirationDate = "2024-12-31T23:59:59Z"
});

Console.WriteLine(result.Ok); // True
```

**Required Fields:**

* `Title` (string, max 255 chars) - The title of the memo
* `Content` (string) - The full content of the memo

**Optional Fields:**

* `Metadata` (`Dictionary<string, object>`) - Custom JSON metadata
* `ReferenceId` (string, max 255 chars) - An ID from your side that you can use to match Skald memo UUIDs with documents on your end
* `Tags` (`List<string>`) - Tags for categorization
* `Source` (string, max 255 chars) - An indication of the source of this content, useful when building integrations
* `ExpirationDate` (string) - ISO 8601 timestamp for automatic memo expiration

#### Get a Memo

Retrieve a memo by its UUID or your reference ID:

```csharp theme={null}
// Get by UUID
var memo = await client.GetMemoAsync("550e8400-e29b-41d4-a716-446655440000");

// Get by reference ID
var memo = await client.GetMemoAsync("external-id-123", IdType.ReferenceId);

Console.WriteLine(memo.Title);
Console.WriteLine(memo.Content);
Console.WriteLine(memo.Summary);
Console.WriteLine(string.Join(", ", memo.Tags.ConvertAll(t => t.Tag)));
```

The `GetMemoAsync()` method returns complete memo details including content, AI-generated summary, tags, and content chunks.

#### List Memos

List all memos with pagination:

```csharp theme={null}
// Get first page with default page size (20)
var memos = await client.ListMemosAsync();

// Get specific page with custom page size
var memos = await client.ListMemosAsync(new ListMemosParams
{
    Page = 2,
    PageSize = 50
});

Console.WriteLine($"Total memos: {memos.Count}");
Console.WriteLine($"Results: {memos.Results.Count}");
Console.WriteLine($"Next page: {memos.Next}");
```

**Parameters:**

* `Page` (int, optional) - Page number (default: 1)
* `PageSize` (int, optional) - Results per page (default: 20, max: 100)

#### Update a Memo

Update an existing memo by UUID or reference ID:

```csharp theme={null}
// Update by UUID
await client.UpdateMemoAsync("550e8400-e29b-41d4-a716-446655440000", new UpdateMemoData
{
    Title = "Updated Title",
    Metadata = new Dictionary<string, object> { { "status", "reviewed" } }
});

// Update by reference ID and trigger reprocessing
await client.UpdateMemoAsync("external-id-123", new UpdateMemoData
{
    Content = "New content that will be reprocessed"
}, IdType.ReferenceId);
```

**Note:** When you update the `Content` field, the memo will be automatically reprocessed (summary, tags, and chunks regenerated).

**Updatable Fields:**

* `Title` (string)
* `Content` (string)
* `Metadata` (`Dictionary<string, object>`)
* `ClientReferenceId` (string)
* `Source` (string)
* `ExpirationDate` (string)

#### Delete a Memo

Permanently delete a memo and all associated data:

```csharp theme={null}
// Delete by UUID
await client.DeleteMemoAsync("550e8400-e29b-41d4-a716-446655440000");

// Delete by reference ID
await client.DeleteMemoAsync("external-id-123", IdType.ReferenceId);
```

**Warning:** This operation permanently deletes the memo and all related data (content, summary, tags, chunks) and cannot be undone.

### Search Memos

Search through your memos using various search methods with optional filters:

```csharp theme={null}
// Basic semantic search
var results = await client.SearchAsync(new SearchRequest
{
    Query = "quarterly goals",
    SearchMethod = SearchMethod.ChunkVectorSearch,
    Limit = 10
});

// Search with filters
var filtered = await client.SearchAsync(new SearchRequest
{
    Query = "python tutorial",
    SearchMethod = SearchMethod.TitleContains,
    Filters = new List<Filter>
    {
        new Filter
        {
            Field = "source",
            Operator = FilterOperator.Eq,
            Value = "notion",
            FilterType = FilterType.NativeField
        },
        new Filter
        {
            Field = "level",
            Operator = FilterOperator.Eq,
            Value = "beginner",
            FilterType = FilterType.CustomMetadata
        }
    }
});

Console.WriteLine($"Found {filtered.Results.Count} results");
foreach (var memo in filtered.Results)
{
    Console.WriteLine($"- {memo.Title} (distance: {memo.Distance})");
}
```

#### Search Methods

* **`ChunkVectorSearch`** - Semantic search on memo chunks for detailed content search
* **`TitleContains`** - Case-insensitive substring match on memo titles
* **`TitleStartswith`** - Case-insensitive prefix match on memo titles

#### Search Parameters

* `Query` (string, required) - The search query
* `SearchMethod` (SearchMethod, required) - One of the search methods above
* `Limit` (int, optional) - Maximum results to return (1-50, default 10)
* `Filters` (`List<Filter>`, optional) - Array of filter objects to narrow results

#### Search Response

```csharp theme={null}
public class SearchResult
{
    public string Uuid { get; set; }          // Unique identifier for the memo
    public string Title { get; set; }          // Memo title
    public string Summary { get; set; }        // Auto-generated summary
    public string ContentSnippet { get; set; } // Snippet of the content
    public double? Distance { get; set; }      // Relevance score (0-2, lower is more relevant)
}
```

* `Distance` - A decimal from 0 to 2 determining how close the result was deemed to be to the query when using semantic search. The closer to 0 the more related the content is to the query. `null` if using `TitleContains` or `TitleStartswith`.

### Chat with Your Knowledge Base

Ask questions about your memos using an AI agent. The agent retrieves relevant context and generates answers with inline citations.

#### Non-Streaming Chat

```csharp theme={null}
var result = await client.ChatAsync("What were the main points discussed in the Q1 meeting?");

Console.WriteLine(result.Response);
// "The main points discussed in the Q1 meeting were:
// 1. Revenue targets
// 2. Hiring plans
// 3. Product roadmap"

Console.WriteLine(result.Ok); // true
```

#### Streaming Chat

For real-time responses, use streaming chat:

```csharp theme={null}
await foreach (var evt in client.StreamedChatAsync("What are our quarterly goals?"))
{
    if (evt.Type == "token" && evt.Content != null)
    {
        // Write each token as it arrives
        Console.Write(evt.Content);
    }
    else if (evt.Type == "done")
    {
        Console.WriteLine("\nDone!");
    }
}
```

#### Chat Parameters

* `query` (string, required) - The question to ask
* `filters` (`List<Filter>`, optional) - Array of filter objects to focus chat context on specific sources

#### Chat Response

Non-streaming responses include:

* `Ok` (bool) - Success status
* `Response` (string) - The AI's answer
* `IntermediateSteps` (`List<object>`) - Steps taken by the agent (for debugging)

Streaming responses yield events:

* `{ Type = "token", Content = "..." }` - Each text token as it's generated
* `{ Type = "done" }` - Indicates the stream has finished

### Filters

Filters allow you to narrow down results based on memo metadata. You can filter by native fields or custom metadata fields. Filters are supported in `SearchAsync()`, `ChatAsync()`, `GenerateDocAsync()`, and their streaming variants.

#### Filter Structure

```csharp theme={null}
public class Filter
{
    public string Field { get; set; }           // Field name to filter on
    public FilterOperator Operator { get; set; } // Comparison operator
    public object Value { get; set; }           // Value(s) to compare against
    public FilterType FilterType { get; set; }  // native_field or custom_metadata
}
```

#### Native Fields

Native fields are built-in memo properties:

* `title` - Memo title
* `source` - Source system (e.g., "notion", "confluence")
* `client_reference_id` - Your external reference ID
* `tags` - Memo tags (array)

#### Custom Metadata Fields

You can filter on any field from the `Metadata` object you provided when creating the memo.

#### Filter Operators

* **`Eq`** - Equals (exact match)
* **`Neq`** - Not equals
* **`Contains`** - Contains substring (case-insensitive)
* **`Startswith`** - Starts with prefix (case-insensitive)
* **`Endswith`** - Ends with suffix (case-insensitive)
* **`In`** - Value is in array (requires array value)
* **`NotIn`** - Value is not in array (requires array value)

#### Filter Examples

```csharp theme={null}
// Filter by source
new Filter
{
    Field = "source",
    Operator = FilterOperator.Eq,
    Value = "notion",
    FilterType = FilterType.NativeField
}

// Filter by multiple tags
new Filter
{
    Field = "tags",
    Operator = FilterOperator.In,
    Value = new[] { "security", "compliance" },
    FilterType = FilterType.NativeField
}

// Filter by title containing text
new Filter
{
    Field = "title",
    Operator = FilterOperator.Contains,
    Value = "meeting",
    FilterType = FilterType.NativeField
}

// Filter by custom metadata field
new Filter
{
    Field = "department",
    Operator = FilterOperator.Eq,
    Value = "engineering",
    FilterType = FilterType.CustomMetadata
}

// Exclude specific sources
new Filter
{
    Field = "source",
    Operator = FilterOperator.NotIn,
    Value = new[] { "draft", "archive" },
    FilterType = FilterType.NativeField
}
```

#### Combining Multiple Filters

When you provide multiple filters, they are combined with AND logic (all filters must match):

```csharp theme={null}
var results = await client.SearchAsync(new SearchRequest
{
    Query = "security best practices",
    SearchMethod = SearchMethod.ChunkVectorSearch,
    Filters = new List<Filter>
    {
        new Filter
        {
            Field = "source",
            Operator = FilterOperator.Eq,
            Value = "security-docs",
            FilterType = FilterType.NativeField
        },
        new Filter
        {
            Field = "tags",
            Operator = FilterOperator.In,
            Value = new[] { "approved", "current" },
            FilterType = FilterType.NativeField
        },
        new Filter
        {
            Field = "status",
            Operator = FilterOperator.Neq,
            Value = "draft",
            FilterType = FilterType.CustomMetadata
        }
    }
});
```

#### Filters with Chat

Focus chat context on specific sources:

```csharp theme={null}
var result = await client.ChatAsync(
    query: "What are our security practices?",
    filters: new List<Filter>
    {
        new Filter
        {
            Field = "tags",
            Operator = FilterOperator.In,
            Value = new[] { "security", "compliance" },
            FilterType = FilterType.NativeField
        }
    }
);
```

#### Filters with Document Generation

Control which memos are used for document generation:

```csharp theme={null}
var doc = await client.GenerateDocAsync(
    prompt: "Create an API integration guide",
    rules: "Use technical language with code examples",
    filters: new List<Filter>
    {
        new Filter
        {
            Field = "source",
            Operator = FilterOperator.In,
            Value = new[] { "api-docs", "technical-specs" },
            FilterType = FilterType.NativeField
        },
        new Filter
        {
            Field = "document_type",
            Operator = FilterOperator.Eq,
            Value = "specification",
            FilterType = FilterType.CustomMetadata
        }
    }
);
```

### Error Handling

```csharp theme={null}
try
{
    var result = await client.CreateMemoAsync(new MemoData
    {
        Title = "My Memo",
        Content = "Content here"
    });
    Console.WriteLine("Success");
}
catch (SkaldException ex)
{
    Console.Error.WriteLine($"Error: {ex.Message}");
}
```

### Using Custom HttpClient

If you need to customize the HTTP client (e.g., for proxy settings, custom timeout, or other configurations):

```csharp theme={null}
var httpClient = new HttpClient
{
    Timeout = TimeSpan.FromSeconds(60)
};

// Pass false for disposeHttpClient to prevent the SkaldClient from disposing your HttpClient
using var client = new SkaldClient("your-api-key", httpClient, disposeHttpClient: false);

// ... use the client

httpClient.Dispose(); // You are responsible for disposing the HttpClient
```

## Examples

For complete working examples, see the [examples directory](https://github.com/skaldlabs/skald-csharp/tree/main/examples) in the GitHub repository.

## GitHub Repository

[https://github.com/skaldlabs/skald-csharp](https://github.com/skaldlabs/skald-csharp)


# Go SDK
Source: https://docs.useskald.com/docs/sdks/go

Documentation on how to use the Skald Go SDK.

Go client library for the Skald API.

## Installation

```bash theme={null}
go get github.com/skaldlabs/skald-go
```

## Requirements

* Go 1.18 or higher

## Usage

### Initialize the client

```go theme={null}
import "github.com/skaldlabs/skald-go"

client := skald.NewClient("your-api-key-here")
```

You can optionally specify a custom base URL (e.g., for self-hosted instances):

```go theme={null}
client := skald.NewClient("your-api-key-here", "https://custom-api.example.com")
```

### Memo Management

#### Create a Memo

Create a new memo that will be automatically processed (summarized, tagged, chunked, and indexed for search):

```go theme={null}
refID := "external-id-123"
source := "notion"
expirationDate := time.Now().Add(30 * 24 * time.Hour)

result, err := client.CreateMemo(ctx, skald.MemoData{
    Title:   "Meeting Notes",
    Content: "Full content of the memo...",
    Metadata: map[string]interface{}{
        "type":   "notes",
        "author": "John Doe",
    },
    ReferenceID:    &refID,
    Tags:           []string{"meeting", "q1"},
    Source:         &source,
    ExpirationDate: &expirationDate,
})

if err != nil {
    log.Fatal(err)
}

fmt.Println(result.MemoUUID) // UUID of created memo
```

**Required Fields:**

* `Title` (string, max 255 chars) - The title of the memo
* `Content` (string) - The full content of the memo

**Optional Fields:**

* `Metadata` (map\[string]interface) - Custom JSON metadata
* `ReferenceID` (\*string, max 255 chars) - An ID from your side that you can use to match Skald memo UUIDs with e.g. documents on your end
* `Tags` (\[]string) - Tags for categorization
* `Source` (\*string, max 255 chars) - An indication from your side of the source of this content, useful when building integrations
* `ExpirationDate` (\*time.Time) - Timestamp for automatic memo expiration

#### Create a Memo from File

Upload a document file to create a memo. Supported formats include PDF, DOC, DOCX, and PPTX (max 100MB):

```go theme={null}
title := "Q4 Business Report"
source := "reports"
refID := "report-2024-q4"

result, err := client.CreateMemoFromFile(ctx, "document.pdf", &skald.MemoFileData{
    Title:       &title,
    Source:      &source,
    ReferenceID: &refID,
    Tags:        []string{"business", "quarterly"},
    Metadata: map[string]interface{}{
        "year":    2024,
        "quarter": "Q4",
    },
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Uploaded memo UUID: %s\n", result.MemoUUID)
```

**Parameters:**

* `filePath` (string, required) - Path to the file to upload
* `memoData` (\*MemoFileData, optional) - Optional metadata for the memo

**MemoFileData Fields (all optional):**

* `Title` (\*string, max 255 chars) - The title of the memo
* `Source` (\*string, max 255 chars) - Source identifier
* `ReferenceID` (\*string, max 255 chars) - Your external reference ID
* `Tags` (\[]string) - Tags for categorization
* `Metadata` (map\[string]interface) - Custom JSON metadata
* `ExpirationDate` (\*time.Time) - Timestamp for automatic memo expiration

**Note:** File uploads are processed asynchronously. Use `CheckMemoStatus()` to monitor processing status.

#### Check Memo Processing Status

Monitor the processing status of a memo, especially useful after uploading files:

```go theme={null}
// Check status by UUID
status, err := client.CheckMemoStatus(ctx, memoUUID)

// Check status by reference ID
status, err := client.CheckMemoStatus(ctx, "report-2024-q4", skald.IDTypeReferenceID)

if err != nil {
    log.Fatal(err)
}

switch status.Status {
case skald.MemoStatusProcessed:
    fmt.Println("Memo is ready!")
case skald.MemoStatusProcessing:
    fmt.Println("Still processing...")
case skald.MemoStatusError:
    fmt.Printf("Processing failed: %s\n", *status.ErrorReason)
}
```

**Status Values:**

* `MemoStatusProcessing` - The memo is currently being processed
* `MemoStatusProcessed` - The memo has been successfully processed and is ready
* `MemoStatusError` - Processing failed (check `ErrorReason` field for details)

**Example: Polling for completion**

```go theme={null}
maxAttempts := 30
pollInterval := 2 * time.Second

for attempt := 1; attempt <= maxAttempts; attempt++ {
    status, err := client.CheckMemoStatus(ctx, memoUUID)
    if err != nil {
        log.Fatal(err)
    }

    if status.Status == skald.MemoStatusProcessed {
        fmt.Println("Processing complete!")
        break
    } else if status.Status == skald.MemoStatusError {
        log.Fatalf("Processing failed: %s", *status.ErrorReason)
    }

    time.Sleep(pollInterval)
}
```

#### Get a Memo

Retrieve a memo by its UUID or your reference ID:

```go theme={null}
// Get by UUID
memo, err := client.GetMemo(ctx, "550e8400-e29b-41d4-a716-446655440000")

// Get by reference ID
memo, err := client.GetMemo(ctx, "external-id-123", skald.IDTypeReferenceID)

if err != nil {
    log.Fatal(err)
}

fmt.Println(memo.Title)
fmt.Println(memo.Content)
fmt.Println(memo.Summary)
fmt.Println(memo.Tags)
fmt.Println(memo.Chunks)
```

The `GetMemo()` method returns complete memo details including content, AI-generated summary, tags, and content chunks.

#### List Memos

List all memos with pagination:

```go theme={null}
// Get first page with default page size (20)
memos, err := client.ListMemos(ctx, nil)

// Get specific page with custom page size
page := 2
pageSize := 50
memos, err := client.ListMemos(ctx, &skald.ListMemosParams{
    Page:     &page,
    PageSize: &pageSize,
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total memos: %d\n", memos.Count)
fmt.Printf("Results: %d\n", len(memos.Results))
```

**Parameters:**

* `Page` (\*int, optional) - Page number (default: 1)
* `PageSize` (\*int, optional) - Results per page (default: 20, max: 100)

#### Update a Memo

Update an existing memo by UUID or reference ID:

```go theme={null}
// Update by UUID
title := "Updated Title"
_, err := client.UpdateMemo(ctx, "550e8400-e29b-41d4-a716-446655440000", skald.UpdateMemoData{
    Title: &title,
    Metadata: map[string]interface{}{
        "status": "reviewed",
    },
})

// Update by reference ID and trigger reprocessing
content := "New content that will be reprocessed"
_, err := client.UpdateMemo(ctx, "external-id-123", skald.UpdateMemoData{
    Content: &content,
}, skald.IDTypeReferenceID)
```

**Note:** When you update the `Content` field, the memo will be automatically reprocessed (summary, tags, and chunks regenerated).

**Updatable Fields:**

* `Title` (\*string)
* `Content` (\*string)
* `Metadata` (map\[string]interface)
* `ClientReferenceID` (\*string)
* `Source` (\*string)
* `ExpirationDate` (\*time.Time)

#### Delete a Memo

Permanently delete a memo and all associated data:

```go theme={null}
// Delete by UUID
err := client.DeleteMemo(ctx, "550e8400-e29b-41d4-a716-446655440000")

// Delete by reference ID
err := client.DeleteMemo(ctx, "external-id-123", skald.IDTypeReferenceID)

if err != nil {
    log.Fatal(err)
}
```

**Warning:** This operation permanently deletes the memo and all related data (content, summary, tags, chunks) and cannot be undone.

### Search Memos

Search through your memos using semantic search with optional filters:

```go theme={null}
// Basic semantic search
limit := 10
results, err := client.Search(ctx, skald.SearchRequest{
    Query:        "quarterly goals",
    Limit:        &limit,
})

// Search with filters
filtered, err := client.Search(ctx, skald.SearchRequest{
    Query:        "python tutorial",
    Filters: []skald.Filter{
        {
            Field:      "source",
            Operator:   skald.FilterOperatorEq,
            Value:      "notion",
            FilterType: skald.FilterTypeNativeField,
        },
        {
            Field:      "level",
            Operator:   skald.FilterOperatorEq,
            Value:      "beginner",
            FilterType: skald.FilterTypeCustomMetadata,
        },
    },
})

if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d results\n", len(filtered.Results))
for _, memo := range filtered.Results {
    fmt.Printf("- %s (distance: %.4f)\n", memo.Title, *memo.Distance)
}
```

#### Search Parameters

* `Query` (string, required) - The search query
* `Limit` (\*int, optional) - Maximum results to return (1-50, default 10)
* `Filters` (\[]Filter, optional) - Array of filter objects to narrow results (see Filters section below)

#### Search Response

```go theme={null}
type SearchResponse struct {
    Results []SearchResult
}

type SearchResult struct {
    UUID           string
    Title          string
    Summary        string
    ContentSnippet string
    Distance       *float64  // Only populated for semantic search
}
```

* `UUID` - Unique identifier for the memo
* `Title` - Memo title
* `Summary` - Auto-generated summary for the memo
* `ContentSnippet` - A snippet containing the beginning of the memo
* `Distance` - A decimal from 0 to 2 determining how close the result was deemed to be to the query.

### Chat with Your Knowledge Base

Ask questions about your memos using an AI agent. The agent retrieves relevant context and generates answers with inline citations.

#### Non-Streaming Chat

```go theme={null}
result, err := client.Chat(ctx, skald.ChatParams{
    Query: "What were the main points discussed in the Q1 meeting?",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.Response)
// "The main points discussed in the Q1 meeting were:
// 1. Revenue targets
// 2. Hiring plans
// 3. Product roadmap"

fmt.Println(result.OK) // true
```

#### Streaming Chat

For real-time responses, use streaming chat:

```go theme={null}
eventChan, errChan := client.StreamedChat(ctx, skald.ChatParams{
    Query: "What are our quarterly goals?",
})

for event := range eventChan {
    if event.Type == "token" && event.Content != nil {
        // Write each token as it arrives
        fmt.Print(*event.Content)
    } else if event.Type == "done" {
        fmt.Println("\nDone!")
        break
    }
}

// Check for errors
select {
case err := <-errChan:
    if err != nil {
        log.Fatal(err)
    }
default:
}
```

#### Chat Parameters

* `query` (string, required) - The question to ask
* `system_prompt` (string, optional) - A system prompt to guide the chat agent's behavior
* `filters` (\[]Filter, optional) - Array of filter objects to focus chat context on specific sources (see Filters section below)

#### Chat Response

Non-streaming responses include:

* `OK` (bool) - Success status
* `Response` (string) - The AI's answer
* `IntermediateSteps` (\[]interface) - Steps taken by the agent (for debugging)

Streaming responses yield events:

* `{ Type: "token", Content: *string }` - Each text token as it's generated
* `{ Type: "done" }` - Indicates the stream has finished

### Filters

Filters allow you to narrow down results based on memo metadata. You can filter by native fields or custom metadata fields. Filters are supported in `Search()`, `Chat()`, and their streaming variants.

See [Filters](/docs/api-reference/filters) for complete documentation.

#### Filter Structure

```go theme={null}
type Filter struct {
    Field      string         // Field name to filter on
    Operator   FilterOperator // Comparison operator
    Value      interface{}    // Value(s) to compare against (string or []string)
    FilterType FilterType     // 'native_field' or 'custom_metadata'
}
```

#### Native Fields

Native fields are built-in memo properties:

* `title` - Memo title
* `source` - Source system (e.g., "notion", "confluence")
* `client_reference_id` - Your external reference ID
* `tags` - Memo tags (array)

#### Custom Metadata Fields

You can filter on any field from the `Metadata` map you provided when creating the memo.

#### Filter Operators

* **`FilterOperatorEq`** - Equals (exact match)
* **`FilterOperatorNeq`** - Not equals
* **`FilterOperatorContains`** - Contains substring (case-insensitive)
* **`FilterOperatorStartsWith`** - Starts with prefix (case-insensitive)
* **`FilterOperatorEndsWith`** - Ends with suffix (case-insensitive)
* **`FilterOperatorIn`** - Value is in array (requires array value)
* **`FilterOperatorNotIn`** - Value is not in array (requires array value)

#### Filter Examples

```go theme={null}
// Filter by source
skald.Filter{
    Field:      "source",
    Operator:   skald.FilterOperatorEq,
    Value:      "notion",
    FilterType: skald.FilterTypeNativeField,
}

// Filter by multiple tags
skald.Filter{
    Field:      "tags",
    Operator:   skald.FilterOperatorIn,
    Value:      []string{"security", "compliance"},
    FilterType: skald.FilterTypeNativeField,
}

// Filter by title containing text
skald.Filter{
    Field:      "title",
    Operator:   skald.FilterOperatorContains,
    Value:      "meeting",
    FilterType: skald.FilterTypeNativeField,
}

// Filter by custom metadata field
skald.Filter{
    Field:      "department",
    Operator:   skald.FilterOperatorEq,
    Value:      "engineering",
    FilterType: skald.FilterTypeCustomMetadata,
}

// Exclude specific sources
skald.Filter{
    Field:      "source",
    Operator:   skald.FilterOperatorNotIn,
    Value:      []string{"draft", "archive"},
    FilterType: skald.FilterTypeNativeField,
}
```

#### Combining Multiple Filters

When you provide multiple filters, they are combined with AND logic (all filters must match):

```go theme={null}
results, err := client.Search(ctx, skald.SearchRequest{
    Query:        "security best practices",
    Filters: []skald.Filter{
        {
            Field:      "source",
            Operator:   skald.FilterOperatorEq,
            Value:      "security-docs",
            FilterType: skald.FilterTypeNativeField,
        },
        {
            Field:      "tags",
            Operator:   skald.FilterOperatorIn,
            Value:      []string{"approved", "current"},
            FilterType: skald.FilterTypeNativeField,
        },
        {
            Field:      "status",
            Operator:   skald.FilterOperatorNeq,
            Value:      "draft",
            FilterType: skald.FilterTypeCustomMetadata,
        },
    },
})
```

#### Filters with Chat

Focus chat context on specific sources:

```go theme={null}
result, err := client.Chat(ctx, skald.ChatParams{
    Query: "What are our security practices?",
    Filters: []skald.Filter{
        {
            Field:      "tags",
            Operator:   skald.FilterOperatorIn,
            Value:      []string{"security", "compliance"},
            FilterType: skald.FilterTypeNativeField,
        },
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Response)
```

### Error Handling

```go theme={null}
result, err := client.CreateMemo(ctx, skald.MemoData{
    Title:   "My Memo",
    Content: "Content here",
})

if err != nil {
    log.Printf("Error: %v", err)
    return
}

fmt.Println("Success:", result)
```

## Type Definitions

The SDK exports the following types for use in your Go code:

```go theme={null}
// ID and filter types
type IDType string
type FilterOperator string
type FilterType string

// Memo types
type MemoData struct { ... }
type MemoFileData struct { ... }
type CreateMemoResponse struct { ... }
type UpdateMemoData struct { ... }
type UpdateMemoResponse struct { ... }
type Memo struct { ... }
type MemoListItem struct { ... }
type ListMemosParams struct { ... }
type ListMemosResponse struct { ... }
type MemoTag struct { ... }
type MemoChunk struct { ... }
type MemoStatus string
type MemoStatusResponse struct { ... }

// Filter types
type Filter struct { ... }

// Search types
type SearchRequest struct { ... }
type SearchResponse struct { ... }
type SearchResult struct { ... }

// Chat types
type ChatRequest struct { ... }
type ChatResponse struct { ... }
type ChatStreamEvent struct { ... }
```

See the [types.go](https://github.com/skaldlabs/skald-go/blob/main/types.go) file for complete type definitions.

## Complete Example

```go theme={null}
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/skaldlabs/skald-go"
)

func main() {
    // Initialize client
    client := skald.NewClient("your-api-key-here")
    ctx := context.Background()

    // Create a memo
    refID := "example-123"
    source := "example-app"
    result, err := client.CreateMemo(ctx, skald.MemoData{
        Title:   "Go Programming Best Practices",
        Content: "Go is a statically typed, compiled programming language...",
        Metadata: map[string]interface{}{
            "category": "programming",
            "level":    "intermediate",
        },
        ReferenceID: &refID,
        Tags:        []string{"go", "programming"},
        Source:      &source,
    })

    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created memo: %+v\n", result)

    // Search for memos
    limit := 5
    searchResults, err := client.Search(ctx, skald.SearchRequest{
        Query:        "golang best practices",
        Limit:        &limit,
    })

    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d results:\n", len(searchResults.Results))
    for _, result := range searchResults.Results {
        fmt.Printf("- %s\n", result.Title)
    }

    // Chat with knowledge base
    chatResp, err := client.Chat(ctx, skald.ChatParams{
        Query: "What are Go best practices?",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Answer: %s\n", chatResp.Response)

}
```


# Skald MCP
Source: https://docs.useskald.com/docs/sdks/mcp

Documentation on how to install and use the Skald MCP

## Features

The Skald MCP server allows you to interact with your Skald knowledge base through a familiar interface like Cursor or Claude.

It let's you chat with your knowledge base, search through your memos, and create new memos.

The Skald MCP server provides three powerful tools:

### 1. **skald-chat**

Ask Skald questions about your knowledge base in natural language.

### 2. **skald-search**

Search through your memos using multiple methods:

* **Semantic search** (`chunk_vector_search`) - Find relevant content by meaning
* **Title contains** (`title_contains`) - Case-insensitive substring matching
* **Title starts with** (`title_startswith`) - Case-insensitive prefix matching

### 3. **skald-create-memo**

Create new memos that are automatically processed, summarized, tagged, chunked, and indexed for search.

## Setup

### Prerequisites

1. A Skald account with an API key. Get yours at [platform.useskald.com](https://platform.useskald.com/)
2. Node.js 18.0.0 or higher

### Installation

1. Clone this repository:

```bash theme={null}
git clone https://github.com/skaldlabs/skald-mcp
```

2. Change directory to the project:

```bash theme={null}
cd skald-mcp
```

3. Install dependencies:

```bash theme={null}
npm install
```

4. Build the project:

```bash theme={null}
npm run build
```

## Configuration

### Cursor

1. Open Cursor Settings (`cmd`+`shift`+`p` on macOS or `ctrl`+`shift`+`p` on Windows → "Cursor Settings")
2. Select "MCP" from the left sidebar and click "Add new global MCP server"
3. Add the following configuration:

```json theme={null}
{
  "mcpServers": {
    "skald": {
      "type": "command",
      "command": "node ABSOLUTE_PATH_TO_PROJECT/build/index.js --key=YOUR_SKALD_API_KEY"
    }
  }
}
```

Replace:

* `ABSOLUTE_PATH_TO_PROJECT` with the full path to your `skald-mcp` directory
* `YOUR_SKALD_API_KEY` with your Skald API key

**Tip:** Right-click on `/build/index.js` in Cursor and select "Copy Path" to get the absolute path.

### Claude Desktop

1. Open Claude Desktop settings and navigate to the "Developer" tab
2. Click "Edit Config"
3. Add the following configuration:

```json theme={null}
{
  "mcpServers": {
    "skald": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_PROJECT/build/index.js"
      ],
      "env": {
        "SKALD_API_KEY": "YOUR_SKALD_API_KEY"
      }
    }
  }
}
```

Replace:

* `ABSOLUTE_PATH_TO_PROJECT` with the full path to your `skald-mcp` directory
* `YOUR_SKALD_API_KEY` with your Skald API key

**Environment variables:**

* `SKALD_API_KEY`: Your Skald API key (required)

4. Restart Claude Desktop

## Usage Examples

### Chat with your knowledge base

```
Ask Cursor/Claude: "Check Skald for what are the instructions for running our Django server locally."
```

The assistant will query your Skald knowledge base and return an answer.

### Search for memos

```
Ask Cursor/Claude: "Search Skald for the docs about our product vision"
```

The assistant will use the `skald-search` tool with semantic search to find relevant memos.

### Create a new memo

```
Ask Cursor/Claude: "Generate an API reference for my endpoints and upload it to Skald"
```

The assistant will create a new memo in your Skald knowledge base, which will be automatically processed and made searchable.

## Tool Parameters

### skald-chat

| Parameter    | Type   | Required | Description                                             |
| ------------ | ------ | -------- | ------------------------------------------------------- |
| `query`      | string | Yes      | The question to ask your knowledge base                 |
| `project_id` | string | No       | Project UUID (required when using Token Authentication) |

### skald-search

| Parameter       | Type      | Required | Description                                                         |
| --------------- | --------- | -------- | ------------------------------------------------------------------- |
| `query`         | string    | Yes      | The search query                                                    |
| `search_method` | enum      | Yes      | One of: `chunk_vector_search`, `title_contains`, `title_startswith` |
| `limit`         | number    | No       | Maximum results to return (1-50, default 10)                        |
| `tags`          | string\[] | No       | Filter results by tags                                              |

### skald-create-memo

| Parameter      | Type      | Required | Description                                             |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| `title`        | string    | Yes      | The title of the memo (max 255 characters)              |
| `content`      | string    | Yes      | The full content of the memo                            |
| `project_id`   | string    | No       | Project UUID (required when using Token Authentication) |
| `metadata`     | object    | No       | Custom JSON metadata                                    |
| `reference_id` | string    | No       | External reference ID to match with your documents      |
| `tags`         | string\[] | No       | Tags for categorization                                 |
| `source`       | string    | No       | Source of the content (useful for integrations)         |

## Development

### Build

```bash theme={null}
npm run build
```

### Lint

```bash theme={null}
npm run lint
```

### Fix linting issues

```bash theme={null}
npm run lint:fix
```

## Troubleshooting

### API Key Issues

If you get an error about a missing API key:

* For Cursor: Ensure the `--key` argument is set in your config
* For Claude Desktop: Ensure `SKALD_API_KEY` is set in the env section

### Module Not Found

If you see "Cannot find module '@skald-labs/skald-node'":

```bash theme={null}
npm install
npm run build
```

### Connection Issues

Check the debug logs:

* Cursor: Check the MCP server logs in Cursor settings
* Claude Desktop: Check the logs in Claude Desktop developer settings


# NodeJS SDK
Source: https://docs.useskald.com/docs/sdks/node

Documentation on how to use the Skald NodeJS SDK.

Node.js client library for the Skald API.

## Installation

```bash theme={null}
npm install @skald-labs/skald-node
```

## Requirements

* Node 18.0.0 or higher

## Usage

### Initialize the client

```javascript theme={null}
import { Skald } from '@skald-labs/skald-node';

const skald = new Skald('your-api-key-here');
```

### Memo Management

#### Create a Memo

Create a new memo that will be automatically processed (summarized, tagged, chunked, and indexed for search):

```javascript theme={null}
const result = await skald.createMemo({
  title: 'Meeting Notes',
  content: 'Full content of the memo...',
  metadata: {
    type: 'notes',
    author: 'John Doe'
  },
  reference_id: 'external-id-123',
  tags: ['meeting', 'q1'],
  source: 'notion',
  expiration_date: '2024-12-31T23:59:59Z'
});

console.log(result); // { memo_uuid: '550e8400-e29b-41d4-a716-446655440000' }
```

**Required Fields:**

* `title` (string, max 255 chars) - The title of the memo
* `content` (string) - The full content of the memo

**Optional Fields:**

* `project_id` (string) - Project UUID (required when using Token Authentication)
* `metadata` (object) - Custom JSON metadata
* `reference_id` (string, max 255 chars) - An ID from your side that you can use to match Skald memo UUIDs with e.g. documents on your end
* `tags` (array of strings) - Tags for categorization
* `source` (string, max 255 chars) - An indication from your side of the source of this content, useful when building integrations
* `expiration_date` (string) - ISO 8601 timestamp for automatic memo expiration

#### Create a Memo from File Upload

Upload a document file (PDF, DOC, DOCX, PPTX) that will be processed asynchronously and converted into a memo:

```javascript theme={null}
import * as fs from 'fs';

const fileBuffer = fs.readFileSync('./document.pdf');

const result = await skald.createMemoFromFile({
  file: fileBuffer,
  filename: 'document.pdf',
  metadata: {
    type: 'report',
    department: 'engineering'
  },
  tags: ['report', '2024'],
  source: 'google-drive',
  reference_id: 'external-file-123'
});

console.log(result); // { ok: true, memo_uuid: '550e8400-e29b-41d4-a716-446655440000' }

// Poll for processing status
const status = await skald.checkMemoStatus(result.memo_uuid);
console.log(status.status); // 'processing' | 'processed' | 'error'
```

**Supported File Types:**

* PDF (.pdf)
* Microsoft Word (.doc, .docx)
* Microsoft PowerPoint (.pptx)
* Maximum file size: 100MB

**Required Fields:**

* `file` (Buffer | Blob) - The file content
* `filename` (string) - The name of the file including extension

**Optional Fields:**

* `reference_id` (string, max 255 chars) - Your external reference ID
* `metadata` (object) - Custom JSON metadata
* `tags` (array of strings) - Tags for categorization
* `source` (string, max 255 chars) - Source system identifier

**Note:** File processing is asynchronous. Use `checkMemoStatus()` to monitor the processing status.

#### Check Memo Processing Status

Monitor the processing status of a memo, especially useful after uploading files:

```javascript theme={null}
// Check status by UUID
const status = await skald.checkMemoStatus('550e8400-e29b-41d4-a716-446655440000');
console.log(status.status); // 'processing' | 'processed' | 'error'

if (status.status === 'error') {
  console.error('Processing failed:', status.error_reason);
}

// Check by reference ID
const status2 = await skald.checkMemoStatus('external-id-123', 'reference_id');

// Poll until processing completes
while (true) {
  const status = await skald.checkMemoStatus(memoUuid);

  if (status.status === 'processed') {
    console.log('Processing complete!');
    break;
  } else if (status.status === 'error') {
    console.error('Processing failed:', status.error_reason);
    break;
  }

  // Wait 2 seconds before checking again
  await new Promise(resolve => setTimeout(resolve, 2000));
}
```

**Status Values:**

* `processing` - The memo is currently being processed (parsed, summarized, chunked, indexed)
* `processed` - Processing completed successfully, memo is ready to use
* `error` - An error occurred during processing, check `error_reason` for details

**Parameters:**

* `memoId` (string, required) - The memo UUID or client reference ID
* `idType` (string, optional) - Either `'memo_uuid'` or `'reference_id'` (default: `'memo_uuid'`)

#### Get a Memo

Retrieve a memo by its UUID or your reference ID:

```javascript theme={null}
// Get by UUID
const memo = await skald.getMemo('550e8400-e29b-41d4-a716-446655440000');

// Get by reference ID
const memo = await skald.getMemo('external-id-123', 'reference_id');

console.log(memo.title);
console.log(memo.content);
console.log(memo.summary);
console.log(memo.tags);
console.log(memo.chunks);
```

The `getMemo()` method returns complete memo details including content, AI-generated summary, tags, and content chunks.

#### List Memos

List all memos with pagination:

```javascript theme={null}
// Get first page with default page size (20)
const memos = await skald.listMemos();

// Get specific page with custom page size
const memos = await skald.listMemos({ page: 2, page_size: 50 });

console.log(`Total memos: ${memos.count}`);
console.log(`Results: ${memos.results.length}`);
console.log(`Next page: ${memos.next}`);
```

**Parameters:**

* `page` (number, optional) - Page number (default: 1)
* `page_size` (number, optional) - Results per page (default: 20, max: 100)

#### Update a Memo

Update an existing memo by UUID or reference ID:

```javascript theme={null}
// Update by UUID
await skald.updateMemo('550e8400-e29b-41d4-a716-446655440000', {
  title: 'Updated Title',
  metadata: { status: 'reviewed' }
});

// Update by reference ID and trigger reprocessing
await skald.updateMemo('external-id-123', {
  content: 'New content that will be reprocessed'
}, 'reference_id');
```

**Note:** When you update the `content` field, the memo will be automatically reprocessed (summary, tags, and chunks regenerated).

**Updatable Fields:**

* `title` (string)
* `content` (string)
* `metadata` (object)
* `client_reference_id` (string)
* `source` (string)
* `expiration_date` (string)

#### Delete a Memo

Permanently delete a memo and all associated data:

```javascript theme={null}
// Delete by UUID
await skald.deleteMemo('550e8400-e29b-41d4-a716-446655440000');

// Delete by reference ID
await skald.deleteMemo('external-id-123', 'reference_id');
```

**Warning:** This operation permanently deletes the memo and all related data (content, summary, tags, chunks) and cannot be undone.

### Search Memos

Search through your memos using semantic search:

```javascript theme={null}
// Basic semantic search
const results = await skald.search({
  query: 'quarterly goals',
  limit: 10
});

// Search with filters
const filtered = await skald.search({
  query: 'python tutorial',
  filters: [
    {
      field: 'source',
      operator: 'eq',
      value: 'notion',
      filter_type: 'native_field'
    },
    {
      field: 'level',
      operator: 'eq',
      value: 'beginner',
      filter_type: 'custom_metadata'
    }
  ]
});

console.log(`Found ${filtered.results.length} results`);
filtered.results.forEach(memo => {
  console.log(`- ${memo.title} (distance: ${memo.distance})`);
});
```

#### Search Parameters

* `query` (string, required) - The search query
* `limit` (integer, optional) - Maximum results to return (1-50, default 10)
* `filters` (array, optional) - Array of filter objects to narrow results (see Filters section below)

#### Search Response

```typescript theme={null}
interface SearchResponse {
  results: Array<{
    memo_uuid: string;
    chunk_uuid: string;
    memo_title: string;
    memo_summary: string;
    content_snippet: string;
    distance: number | null;
  }>;
}
```

* `memo_uuid` - Unique identifier for the memo
* `memo_uuid` - Unique identifier for the chunk
* `memo_title` - Memo title
* `memo_summary` - Auto-generated summary for the memo
* `content_snippet` - A snippet containing the beginning of the chunk content.
* `distance` - A decimal from 0 to 2 determining how close the result was deemed to be to the query when using semantic search (`chunk_vector_search`). The closer to 0 the more related the content is to the query. `null` if using `title_contains` or `title_startswith`.

### Chat with Your Knowledge Base

Ask questions about your memos using an AI agent. The agent retrieves relevant context and generates answers with inline citations.

#### Non-Streaming Chat

```javascript theme={null}
const result = await skald.chat({
  query: 'What were the main points discussed in the Q1 meeting?'
});

console.log(result.response);
// "The main points discussed in the Q1 meeting were:
// 1. Revenue targets
// 2. Hiring plans
// 3. Product roadmap"

console.log(result.ok); // true
```

#### Streaming Chat

For real-time responses, use streaming chat:

```javascript theme={null}
const stream = skald.streamedChat({
  query: 'What are our quarterly goals?'
});

for await (const event of stream) {
  if (event.type === 'token') {
    // Write each token as it arrives
    process.stdout.write(event.content);
  } else if (event.type === 'done') {
    console.log('\nDone!');
  }
}
```

#### Chat Parameters

* `query` (string, required) - The question to ask
* `system_prompt` (string, optional) - A system prompt to guide the AI's behavior
* `filters` (array, optional) - Array of filter objects to focus chat context on specific sources (see Filters section below)
* `project_id` (string, optional) - Project UUID (required when using Token Authentication)

#### Chat Response

Non-streaming responses include:

* `ok` (boolean) - Success status
* `response` (string) - The AI's answer
* `intermediate_steps` (array) - Steps taken by the agent (for debugging)

Streaming responses yield events:

* `{ type: 'token', content: string }` - Each text token as it's generated
* `{ type: 'done' }` - Indicates the stream has finished

### Filters

Filters allow you to narrow down results based on memo metadata. You can filter by native fields or custom metadata fields. Filters are supported in `search()`, `chat()`, `generateDoc()`, and their streaming variants.

See [Filters](/docs/api-reference/filters) for complete documentation.

#### Filter Structure

```typescript theme={null}
interface Filter {
  field: string;                      // Field name to filter on
  operator: FilterOperator;           // Comparison operator
  value: string | string[];           // Value(s) to compare against
  filter_type: 'native_field' | 'custom_metadata';
}
```

#### Native Fields

Native fields are built-in memo properties:

* `title` - Memo title
* `source` - Source system (e.g., "notion", "confluence")
* `client_reference_id` - Your external reference ID
* `tags` - Memo tags (array)

#### Custom Metadata Fields

You can filter on any field from the `metadata` object you provided when creating the memo.

#### Filter Operators

* **`eq`** - Equals (exact match)
* **`neq`** - Not equals
* **`contains`** - Contains substring (case-insensitive)
* **`startswith`** - Starts with prefix (case-insensitive)
* **`endswith`** - Ends with suffix (case-insensitive)
* **`in`** - Value is in array (requires array value)
* **`not_in`** - Value is not in array (requires array value)

#### Filter Examples

```javascript theme={null}
// Filter by source
{
  field: 'source',
  operator: 'eq',
  value: 'notion',
  filter_type: 'native_field'
}

// Filter by multiple tags
{
  field: 'tags',
  operator: 'in',
  value: ['security', 'compliance'],
  filter_type: 'native_field'
}

// Filter by title containing text
{
  field: 'title',
  operator: 'contains',
  value: 'meeting',
  filter_type: 'native_field'
}

// Filter by custom metadata field
{
  field: 'department',
  operator: 'eq',
  value: 'engineering',
  filter_type: 'custom_metadata'
}

// Exclude specific sources
{
  field: 'source',
  operator: 'not_in',
  value: ['draft', 'archive'],
  filter_type: 'native_field'
}
```

#### Combining Multiple Filters

When you provide multiple filters, they are combined with AND logic (all filters must match):

```javascript theme={null}
const results = await skald.search({
  query: 'security best practices',
  filters: [
    {
      field: 'source',
      operator: 'eq',
      value: 'security-docs',
      filter_type: 'native_field'
    },
    {
      field: 'tags',
      operator: 'in',
      value: ['approved', 'current'],
      filter_type: 'native_field'
    },
    {
      field: 'status',
      operator: 'neq',
      value: 'draft',
      filter_type: 'custom_metadata'
    }
  ]
});
```

#### Filters with Chat

Focus chat context on specific sources:

```javascript theme={null}
const result = await skald.chat({
  query: 'What are our security practices?',
  filters: [
    {
      field: 'tags',
      operator: 'in',
      value: ['security', 'compliance'],
      filter_type: 'native_field'
    }
  ]
});
```

### Scopes

Scopes provide strict data isolation for multi-tenant applications.

#### Creating Memos with Scopes

```javascript theme={null}
await skald.createMemo({
  title: 'Memo title',
  content: 'Scoped content',
  scopes: { organizationId: '123', admin: 'true' }
});
```

#### Querying with Scopes

When using `chat()` or `search()`, provide the same scopes to access scoped content:

```javascript theme={null}
const response = await skald.chat({
  query: 'what was discussed in the meeting on 2026-01-25?',
  scopes: { organizationId: '123', admin: 'true' }
});
```

Only memos that were created with matching scope values will be included in the context.

If you don't provide any scopes, `chat` will query all memos for its context. However, if you pass any scopes, only memos that match exactly the scopes will be included in the context.

You **must** include all relevant scopes in order for them to have effect. Scopes operate on an AND basis.

For example, a memo with scopes: `{ organizationId: '123', admin: 'true' }` will behave as follows:

* If the query includes `{ organizationId: '123', admin: 'true' }`, the memo will be included in the context.
* If the query includes `{ organizationId: '123' }`, the memo **will be included** in the context.
* If the query includes `{ admin: 'true' }`, the memo **will be included** in the context.
* If the query includes `{ organizationId: '123', admin: false }`, the memo **will not be included** in the context.

### Error Handling

```javascript theme={null}
try {
  const result = await skald.createMemo({
    title: 'My Memo',
    content: 'Content here'
  });
  console.log('Success:', result);
} catch (error) {
  console.error('Error:', error.message);
}
```

## TypeScript Support

This package includes TypeScript type definitions out of the box.

```typescript theme={null}
import {
  Skald,
  MemoData,
  CreateMemoResponse,
  MemoFileData,
  CreateMemoFromFileResponse,
  MemoStatus,
  MemoStatusResponse,
  Memo,
  ListMemosResponse,
  UpdateMemoData,
  UpdateMemoResponse,
  IdType,
  Filter,
  FilterOperator,
  FilterType,
  SearchRequest,
  SearchResponse,
  ChatRequest,
  ChatResponse,
  ChatStreamEvent
} from '@skald-labs/skald-node';

const skald = new Skald('your-api-key-here');

// Create a memo with types
const memoData: MemoData = {
  title: 'My Memo',
  content: 'Content here',
  tags: ['tag1', 'tag2'],
  metadata: { department: 'engineering' }
};

const createResponse: CreateMemoResponse = await skald.createMemo(memoData);

// Get memo with types
const memo: Memo = await skald.getMemo('550e8400-e29b-41d4-a716-446655440000');
const memoByRef: Memo = await skald.getMemo('external-id-123', 'reference_id' as IdType);

// List memos with types
const memos: ListMemosResponse = await skald.listMemos({ page: 1, page_size: 20 });

// Update memo with types
const updateData: UpdateMemoData = {
  title: 'Updated Title',
  metadata: { status: 'reviewed' }
};
const updateResponse: UpdateMemoResponse = await skald.updateMemo(
  '550e8400-e29b-41d4-a716-446655440000',
  updateData
);

// Delete memo
await skald.deleteMemo('550e8400-e29b-41d4-a716-446655440000');

// Upload a file
import * as fs from 'fs';
const fileBuffer = fs.readFileSync('./document.pdf');
const fileData: MemoFileData = {
  file: fileBuffer,
  filename: 'document.pdf',
  metadata: { type: 'report' },
  tags: ['document'],
  source: 'local'
};
const uploadResponse: CreateMemoFromFileResponse = await skald.createMemoFromFile(fileData);

// Check processing status
const statusResponse: MemoStatusResponse = await skald.checkMemoStatus(uploadResponse.memo_uuid);
const status: MemoStatus = statusResponse.status; // 'processing' | 'processed' | 'error'

// Search with filters and types
const filters: Filter[] = [
  {
    field: 'source',
    operator: 'eq' as FilterOperator,
    value: 'notion',
    filter_type: 'native_field' as FilterType
  },
  {
    field: 'department',
    operator: 'eq' as FilterOperator,
    value: 'engineering',
    filter_type: 'custom_metadata' as FilterType
  }
];

const searchRequest: SearchRequest = {
  query: 'quarterly goals',
  limit: 10,
  filters
};

const searchResponse: SearchResponse = await skald.search(searchRequest);

// Chat with filters and types
const chatResponse: ChatResponse = await skald.chat({
  query: 'What are our quarterly goals?',
  filters
});

// Streaming chat with types
const stream = skald.streamedChat({
  query: 'What are our quarterly goals?',
  filters
});

for await (const event of stream) {
  const typedEvent: ChatStreamEvent = event;
  if (typedEvent.type === 'token') {
    process.stdout.write(typedEvent.content || '');
  }
}

```


# PHP SDK
Source: https://docs.useskald.com/docs/sdks/php

Documentation on how to use the Skald PHP SDK.

## Requirements

* PHP 8.1 or higher
* cURL extension
* JSON extension

## Installation

Install via Composer:

```bash theme={null}
composer require skald/skald-php
```

## Quick Start

```php theme={null}
<?php

require 'vendor/autoload.php';

use Skald\Skald;
use Skald\Types\MemoData;
use Skald\Types\UpdateMemoData;
use Skald\Types\SearchRequest;
use Skald\Types\SearchMethod;
use Skald\Types\ChatRequest;
use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Initialize the client
$skald = new Skald('sk_proj_your_api_key');

// Create a memo
$result = $skald->createMemo(new MemoData(
    title: 'Meeting Notes - Q1 Planning',
    content: 'Discussed quarterly goals, hiring plans, and budget allocation...',
    tags: ['meeting', 'planning', 'q1'],
    source: 'notion'
));

// Search for memos
$results = $skald->search(new SearchRequest(
    query: 'quarterly goals',
    searchMethod: SearchMethod::CHUNK_VECTOR_SEARCH,
    limit: 10,
    filters: [
        Filter::nativeField('tags', FilterOperator::IN, ['planning', 'q1'])
    ]
));

foreach ($results->results as $result) {
    echo "Title: {$result->title}\n";
    echo "Summary: {$result->summary}\n";
    echo "Relevance: {$result->distance}\n\n";
}

// Ask questions about your knowledge base
$response = $skald->chat(new ChatRequest(
    query: 'What are our main goals for Q1?'
));

echo $response->response; // "The main Q1 goals are..."
```

## API Reference

### Client Initialization

```php theme={null}
$skald = new Skald(string $apiKey, ?string $baseUrl = null);
```

* `$apiKey`: Your Skald API key (required)
* `$baseUrl`: Optional custom API base URL (defaults to `https://api.useskald.com`)

### Creating Memos

```php theme={null}
$response = $skald->createMemo(MemoData $memoData): CreateMemoResponse;
```

**Parameters:**

```php theme={null}
new MemoData(
    title: string,              // Required - memo title (max 255 chars)
    content: string,            // Required - memo content
    metadata: ?array = null,    // Optional - custom JSON metadata
    reference_id: ?string = null, // Optional - external ID mapping
    tags: ?array = null,        // Optional - array of tags
    source: ?string = null      // Optional - source system (e.g., "notion")
);
```

**Example:**

```php theme={null}
$result = $skald->createMemo(new MemoData(
    title: 'Product Requirements',
    content: 'The new mobile app should support offline mode...',
    metadata: ['author' => 'John Doe', 'version' => '1.0'],
    tags: ['product', 'mobile', 'requirements'],
    source: 'confluence'
));

// Returns: CreateMemoResponse { ok: true }
```

### Updating Memos

```php theme={null}
$response = $skald->updateMemo(
    string $memoId,
    UpdateMemoData $updateData,
    string $idType = 'memo_uuid'
): CreateMemoResponse;
```

Update an existing memo with partial or complete changes. All fields are optional - only include the fields you want to update.

**Important**: When `content` is updated, the memo is automatically reprocessed by the API (summary, tags, and chunks are regenerated). Other field updates preserve existing processing results.

**Parameters:**

* `$memoId` (string): The memo UUID or client reference ID
* `$updateData` (UpdateMemoData): The fields to update
* `$idType` (string, optional): Type of identifier - `'memo_uuid'` (default) or `'reference_id'`

```php theme={null}
new UpdateMemoData(
    title: ?string = null,                  // Optional - memo title (max 255 chars)
    content: ?string = null,                // Optional - memo content (triggers reprocessing)
    metadata: ?array = null,                // Optional - custom JSON metadata
    client_reference_id: ?string = null,    // Optional - external ID mapping (max 255 chars)
    source: ?string = null,                 // Optional - source system (max 255 chars)
    expiration_date: ?string = null         // Optional - expiration date (ISO 8601 format)
);
```

**Examples:**

```php theme={null}
use Skald\Types\UpdateMemoData;

// Update by memo UUID (default)
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    title: 'Updated Title'
));

// Update by client reference ID
$skald->updateMemo('external-id-123', new UpdateMemoData(
    title: 'Updated via Reference ID'
), 'reference_id');

// Update content (triggers automatic reprocessing)
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    content: 'New content - this will regenerate summary, tags, and chunks'
));

// Update multiple fields
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    title: 'Updated Title',
    metadata: ['updated_at' => time(), 'editor' => 'Jane'],
    source: 'notion',
    expiration_date: '2025-12-31T23:59:59Z'
));

// Update metadata without triggering reprocessing
$skald->updateMemo('memo-uuid-here', new UpdateMemoData(
    metadata: ['last_viewed' => time(), 'view_count' => 42]
));
```

### Deleting Memos

```php theme={null}
$skald->deleteMemo(
    string $memoId,
    string $idType = 'memo_uuid'
): void;
```

Delete a memo and all its associated data (content, summary, tags, chunks).

**Parameters:**

* `$memoId` (string): The memo UUID or client reference ID
* `$idType` (string, optional): Type of identifier - `'memo_uuid'` (default) or `'reference_id'`

**Examples:**

```php theme={null}
// Delete by memo UUID (default)
$skald->deleteMemo('memo-uuid-here');

// Delete by client reference ID
$skald->deleteMemo('external-id-123', 'reference_id');
```

### Searching Memos

```php theme={null}
$response = $skald->search(SearchRequest $searchParams): SearchResponse;
```

**Search Methods:**

* `SearchMethod::CHUNK_VECTOR_SEARCH` - Semantic search on memo chunks (returns distance scores 0-2)
* `SearchMethod::TITLE_CONTAINS` - Case-insensitive substring match on titles
* `SearchMethod::TITLE_STARTSWITH` - Case-insensitive prefix match on titles

**Parameters:**

```php theme={null}
new SearchRequest(
    query: string,                  // Required - search query
    searchMethod: SearchMethod,     // Required - search method
    limit: ?int = null,            // Optional - results limit (1-50, default 10)
    filters: ?array = null         // Optional - array of Filter objects
);
```

**Example:**

```php theme={null}
use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Basic search
$results = $skald->search(new SearchRequest(
    query: 'product requirements',
    searchMethod: SearchMethod::CHUNK_VECTOR_SEARCH,
    limit: 5
));

foreach ($results->results as $result) {
    echo "UUID: {$result->uuid}\n";
    echo "Title: {$result->title}\n";
    echo "Summary: {$result->summary}\n";
    echo "Snippet: {$result->content_snippet}\n";
    echo "Distance: {$result->distance}\n\n"; // Lower = more relevant
}

// Search with filters
$results = $skald->search(new SearchRequest(
    query: 'product requirements',
    searchMethod: SearchMethod::CHUNK_VECTOR_SEARCH,
    limit: 5,
    filters: [
        Filter::nativeField('tags', FilterOperator::IN, ['product', 'requirements']),
        Filter::nativeField('source', FilterOperator::EQ, 'confluence')
    ]
));
```

See [Filters](/docs/api-reference/filters) for advanced filtering options.

### AI Chat (Non-Streaming)

```php theme={null}
$response = $skald->chat(ChatRequest $chatParams): ChatResponse;
```

**Parameters:**

```php theme={null}
new ChatRequest(
    query: string,              // Required - question to ask
    filters: ?array = null      // Optional - advanced filtering (see Filters)
);
```

**Examples:**

```php theme={null}
use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Basic chat
$response = $skald->chat(new ChatRequest(
    query: 'What are the key features of our mobile app?'
));

echo $response->response;
// Output: "The mobile app has several key features: 1. Offline mode
//          2. Push notifications 3. Biometric authentication"

// Chat with filters to narrow context
$response = $skald->chat(new ChatRequest(
    query: 'What are our Q1 goals?',
    filters: [
        Filter::nativeField('tags', FilterOperator::IN, ['q1', 'planning'])
    ]
));

```

See [Filters](/docs/api-reference/filters) for advanced filtering options.

### AI Chat (Streaming)

```php theme={null}
$stream = $skald->streamedChat(ChatRequest $chatParams): Generator<ChatStreamEvent>;
```

**Example:**

```php theme={null}
$stream = $skald->streamedChat(new ChatRequest(
    query: 'Summarize our product roadmap'
));

foreach ($stream as $event) {
    if ($event->isToken()) {
        echo $event->content; // Print each token as it arrives
    } elseif ($event->isDone()) {
        echo "\nDone!\n";
        break;
    }
}
```

### Document Generation (Non-Streaming)

```php theme={null}
$response = $skald->generateDoc(GenerateDocRequest $generateParams): GenerateDocResponse;
```

**Parameters:**

```php theme={null}
new GenerateDocRequest(
    prompt: string,             // Required - document generation prompt
    rules: ?string = null,      // Optional - style/format rules
    filters: ?array = null      // Optional - advanced filtering (see Filters)
);
```

**Examples:**

```php theme={null}
use Skald\Types\Filter;
use Skald\Types\FilterOperator;

// Basic document generation
$response = $skald->generateDoc(new GenerateDocRequest(
    prompt: 'Create a product requirements document for the mobile app',
    rules: 'Use formal business language. Include sections: Overview, Requirements, Timeline'
));

echo $response->response;
// Outputs a full document with inline citations

// Generate with filters to control context
$response = $skald->generateDoc(new GenerateDocRequest(
    prompt: 'Write a technical specification for our API',
    rules: 'Include Architecture, Endpoints, and Security sections',
    filters: [
        Filter::nativeField('source', FilterOperator::EQ, 'technical-docs')
    ]
));
```

See [Filters](/docs/api-reference/filters) for advanced filtering options.

### Document Generation (Streaming)

```php theme={null}
$stream = $skald->streamedGenerateDoc(GenerateDocRequest $generateParams): Generator<GenerateDocStreamEvent>;
```

**Example:**

```php theme={null}
$stream = $skald->streamedGenerateDoc(new GenerateDocRequest(
    prompt: 'Write a technical specification for our API',
    rules: 'Include Architecture, Endpoints, and Security sections'
));

foreach ($stream as $event) {
    if ($event->isToken()) {
        echo $event->content;
    } elseif ($event->isDone()) {
        echo "\n[Generation complete]\n";
        break;
    }
}
```

## Error Handling

All API errors throw `Skald\Exceptions\SkaldException`:

```php theme={null}
use Skald\Exceptions\SkaldException;

try {
    $result = $skald->createMemo(new MemoData(
        title: 'Test',
        content: 'Content'
    ));
} catch (SkaldException $e) {
    // Error format: "Skald API error (STATUS_CODE): ERROR_MESSAGE"
    echo "Error: " . $e->getMessage();
    echo "HTTP Status: " . $e->getCode();
}
```

## Examples

See the [`examples/` directory on GitHub](https://github.com/skaldlabs/skald-php/tree/main/examples) for complete working examples:

* `create_memo.php` - Creating memos with various options
* `update_memo.php` - Updating existing memos
* `delete_memo.php` - Deleting memos by UUID or reference ID
* `search.php` - All search methods with filters
* `chat.php` - Non-streaming chat
* `chat_streaming.php` - Streaming chat with real-time output
* `generate_doc.php` - Document generation
* `generate_doc_streaming.php` - Streaming document generation


# Python SDK
Source: https://docs.useskald.com/docs/sdks/python

Documentation on how to use the Skald Python SDK.

Python client library for the Skald API.

## Installation

```bash theme={null}
pip install skald-sdk
```

## Requirements

* Python 3.8 or higher

## Usage

### Initialize the client

```python theme={null}
import asyncio
from skald_sdk import Skald

async def main():
    async with Skald('your-api-key-here') as skald:
        # Your code here
        pass

asyncio.run(main())
```

### Memo Management

#### Create a Memo

Create a new memo that will be automatically processed (summarized, tagged, chunked, and indexed for search):

```python theme={null}
result = await skald.create_memo({
    'title': 'Meeting Notes',
    'content': 'Full content of the memo...',
    'metadata': {
        'type': 'notes',
        'author': 'John Doe'
    },
    'reference_id': 'external-id-123',
    'tags': ['meeting', 'q1'],
    'source': 'notion',
    'expiration_date': '2024-12-31T23:59:59Z'
})

print(result)  # { 'memo_uuid': '550e8400-e29b-41d4-a716-446655440000' }
```

**Required Fields:**

* `title` (string, max 255 chars) - The title of the memo
* `content` (string) - The full content of the memo

**Optional Fields:**

* `metadata` (dict) - Custom JSON metadata
* `reference_id` (string, max 255 chars) - An ID from your side that you can use to match Skald memo UUIDs with e.g. documents on your end
* `tags` (list of strings) - Tags for categorization
* `source` (string, max 255 chars) - An indication from your side of the source of this content, useful when building integrations
* `expiration_date` (string) - ISO 8601 timestamp for automatic memo expiration

#### Get a Memo

Retrieve a memo by its UUID or your reference ID:

```python theme={null}
# Get by UUID
memo = await skald.get_memo('550e8400-e29b-41d4-a716-446655440000')

# Get by reference ID
memo = await skald.get_memo('external-id-123', 'reference_id')

print(memo['title'])
print(memo['content'])
print(memo['summary'])
print(memo['tags'])
print(memo['chunks'])
```

The `get_memo()` method returns complete memo details including content, AI-generated summary, tags, and content chunks.

**Memo Response Fields:**

* `uuid` - Unique identifier for the memo
* `title` - Memo title
* `content` - Full memo content
* `summary` - AI-generated summary
* `pending` - Boolean indicating if the memo is still being processed
* `archived` - Boolean indicating if the memo is archived
* `type` - Memo type ("document" or "text")
* `metadata` - Custom metadata object
* `tags` - List of tag objects
* `chunks` - List of content chunk objects

#### List Memos

List all memos with pagination:

```python theme={null}
# Get first page with default page size (20)
memos = await skald.list_memos()

# Get specific page with custom page size
memos = await skald.list_memos({'page': 2, 'page_size': 50})

print(f"Total memos: {memos['count']}")
print(f"Results: {len(memos['results'])}")
print(f"Next page: {memos['next']}")
```

**Parameters:**

* `page` (int, optional) - Page number (default: 1)
* `page_size` (int, optional) - Results per page (default: 20, max: 100)

#### Update a Memo

Update an existing memo by UUID or reference ID:

```python theme={null}
# Update by UUID
await skald.update_memo('550e8400-e29b-41d4-a716-446655440000', {
    'title': 'Updated Title',
    'metadata': {'status': 'reviewed'}
})

# Update by reference ID and trigger reprocessing
await skald.update_memo('external-id-123', {
    'content': 'New content that will be reprocessed'
}, 'reference_id')
```

**Note:** When you update the `content` field, the memo will be automatically reprocessed (summary, tags, and chunks regenerated).

**Updatable Fields:**

* `title` (string)
* `content` (string)
* `metadata` (dict)
* `client_reference_id` (string)
* `source` (string)
* `expiration_date` (string)

#### Delete a Memo

Permanently delete a memo and all associated data:

```python theme={null}
# Delete by UUID
await skald.delete_memo('550e8400-e29b-41d4-a716-446655440000')

# Delete by reference ID
await skald.delete_memo('external-id-123', 'reference_id')
```

**Warning:** This operation permanently deletes the memo and all related data (content, summary, tags, chunks) and cannot be undone.

#### Check Memo Processing Status

After creating or updating a memo (especially when uploading files), it is automatically processed asynchronously (summarized, tagged, and chunked). Use the `check_memo_status()` method to check processing status:

```python theme={null}
# Create a memo
result = await skald.create_memo({
    'title': 'My Document',
    'content': 'Long content that needs processing...'
})
memo_uuid = result['memo_uuid']

# Check processing status
status = await skald.check_memo_status(memo_uuid)

if status['status'] == 'processing':
    print('Memo is still being processed...')
elif status['status'] == 'processed':
    print('Memo is ready!')
    # Now you can retrieve the full memo with summary and tags
    memo = await skald.get_memo(memo_uuid)
    print(f"Summary: {memo['summary']}")
elif status['status'] == 'error':
    print(f"Processing failed: {status['error_reason']}")

# You can also check status by reference ID
status = await skald.check_memo_status('external-id-123', 'reference_id')
```

**Status Response Fields:**

* `memo_uuid` - The memo's UUID
* `status` - Processing state: "processing", "processed", or "error"
* `processing_started_at` - ISO timestamp when processing started
* `processing_completed_at` - ISO timestamp when processing completed (if finished)
* `error_reason` - Error message if status is "error"

**Note:** Most memos are processed within a few seconds, but larger documents may take longer.

### File Uploads

Upload documents (PDF, DOC, DOCX, PPTX) to your Skald knowledge base. Files are automatically processed to extract text, then summarized, tagged, chunked, and indexed for search.

#### Upload a Document

```python theme={null}
# Upload a document file with optional metadata
result = await skald.create_memo_from_file(
    '/path/to/document.pdf',
    {
        'title': 'Q4 Roadmap Presentation',
        'source': 'Product Team',
        'reference_id': 'ROADMAP-Q4-2024',
        'tags': ['roadmap', 'product', 'q4'],
        'metadata': {
            'quarter': 'Q4',
            'year': '2024',
            'department': 'product'
        },
        'expiration_date': '2024-12-31T23:59:59Z'
    }
)

memo_uuid = result['memo_uuid']
print(f"Uploaded document: {memo_uuid}")

# Check processing status
status = await skald.check_memo_status(memo_uuid)
print(f"Processing status: {status['status']}")

# Poll until processing completes
import asyncio
while True:
    status = await skald.check_memo_status(memo_uuid)
    if status['status'] == 'processed':
        print('Processing complete!')
        break
    elif status['status'] == 'error':
        print(f"Error: {status['error_reason']}")
        break
    await asyncio.sleep(2)
```

**Supported File Types:**

* PDF (`.pdf`)
* Microsoft Word (`.doc`, `.docx`)
* Microsoft PowerPoint (`.pptx`)

**File Size Limit:** 100MB per file

**Parameters:**

* `file_path` (string, required) - Path to the file to upload
* `memo_data` (dict, optional) - Optional metadata for the memo:
  * `title` (string) - Title for the memo
  * `source` (string) - Source system identifier
  * `reference_id` (string) - Your external reference ID
  * `tags` (list of strings) - Tags for categorization
  * `metadata` (dict) - Custom JSON metadata
  * `expiration_date` (string) - ISO 8601 timestamp for automatic memo expiration

**Note:** File processing is asynchronous and may take longer than text-based memos depending on file size and complexity. Use `check_memo_status()` to monitor processing progress.

### Search Memos

Search through your memos using semantic search with optional filters:

```python theme={null}
# Basic semantic search
results = await skald.search({
    'query': 'quarterly goals',
    'limit': 10
})

# Search with filters
filtered = await skald.search({
    'query': 'python tutorial',
    'filters': [
        {
            'field': 'source',
            'operator': 'eq',
            'value': 'notion',
            'filter_type': 'native_field'
        },
        {
            'field': 'level',
            'operator': 'eq',
            'value': 'beginner',
            'filter_type': 'custom_metadata'
        }
    ]
})

print(f"Found {len(filtered['results'])} results")
for result in filtered['results']:
    print(f"- {result['memo_title']} (distance: {result['distance']})")
```

#### Search Parameters

* `query` (string, required) - The search query
* `limit` (integer, optional) - Maximum results to return (1-50, default 10)
* `filters` (list, optional) - List of filter objects to narrow results (see Filters section below)

#### Search Response

```python theme={null}
{
    'results': [
        {
            'memo_uuid': str,
            'chunk_uuid': str,
            'memo_title': str,
            'memo_summary': str,
            'content_snippet': str,
            'distance': float | None
        }
    ]
}
```

* `memo_uuid` - Unique identifier for the memo
* `chunk_uuid` - Unique identifier for the chunk
* `memo_title` - Memo title
* `memo_summary` - Auto-generated summary for the memo
* `content_snippet` - A snippet containing content from the matching chunk
* `distance` - A decimal from 0 to 2 determining how close the result was deemed to be to the query. The closer to 0 the more related the content is to the query.

### Chat with Your Knowledge Base

Ask questions about your memos using an AI agent. The agent retrieves relevant context and generates answers with inline citations.

#### Non-Streaming Chat

```python theme={null}
response = await skald.chat({
    'query': 'What were the main points discussed in the Q1 meeting?'
})

print(response['response'])
# "The main points discussed in the Q1 meeting were:
# 1. Revenue targets    
# 2. Hiring plans
# 3. Product roadmap"

print(response['ok'])  # True
```

#### Streaming Chat

For real-time responses, use streaming chat:

```python theme={null}
async for event in skald.streamed_chat({
    'query': 'What are our quarterly goals?'
}):
    if event['type'] == 'token':
        # Print each token as it arrives
        print(event['content'], end='', flush=True)
    elif event['type'] == 'done':
        print('\nDone!')
```

#### Chat Parameters

* `query` (string, required) - The question to ask
* `filters` (list, optional) - List of filter objects to focus chat context on specific sources (see Filters section below)

#### Chat Response

Non-streaming responses include:

* `ok` (bool) - Success status
* `response` (str) - The AI's answer
* `intermediate_steps` (list) - Steps taken by the agent (for debugging)

Streaming responses yield events:

* `{'type': 'token', 'content': str}` - Each text token as it's generated
* `{'type': 'done'}` - Indicates the stream has finished

### Filters

Filters allow you to narrow down results based on memo metadata. You can filter by native fields or custom metadata fields. Filters are supported in `search()`, `chat()`, and their streaming variants.

See [Filters](/docs/api-reference/filters) for complete documentation.

#### Filter Structure

```python theme={null}
{
    'field': str,                       # Field name to filter on
    'operator': str,                    # Comparison operator
    'value': str | list[str],          # Value(s) to compare against
    'filter_type': 'native_field' | 'custom_metadata'
}
```

#### Native Fields

Native fields are built-in memo properties:

* `title` - Memo title
* `source` - Source system (e.g., "notion", "confluence")
* `client_reference_id` - Your external reference ID
* `tags` - Memo tags (list)

#### Custom Metadata Fields

You can filter on any field from the `metadata` dict you provided when creating the memo.

#### Filter Operators

* **`eq`** - Equals (exact match)
* **`neq`** - Not equals
* **`contains`** - Contains substring (case-insensitive)
* **`startswith`** - Starts with prefix (case-insensitive)
* **`endswith`** - Ends with suffix (case-insensitive)
* **`in`** - Value is in list (requires list value)
* **`not_in`** - Value is not in list (requires list value)

#### Filter Examples

```python theme={null}
# Filter by source
{
    'field': 'source',
    'operator': 'eq',
    'value': 'notion',
    'filter_type': 'native_field'
}

# Filter by multiple tags
{
    'field': 'tags',
    'operator': 'in',
    'value': ['security', 'compliance'],
    'filter_type': 'native_field'
}

# Filter by title containing text
{
    'field': 'title',
    'operator': 'contains',
    'value': 'meeting',
    'filter_type': 'native_field'
}

# Filter by custom metadata field
{
    'field': 'department',
    'operator': 'eq',
    'value': 'engineering',
    'filter_type': 'custom_metadata'
}

# Exclude specific sources
{
    'field': 'source',
    'operator': 'not_in',
    'value': ['draft', 'archive'],
    'filter_type': 'native_field'
}
```

#### Combining Multiple Filters

When you provide multiple filters, they are combined with AND logic (all filters must match):

```python theme={null}
results = await skald.search({
    'query': 'security best practices',
    'filters': [
        {
            'field': 'source',
            'operator': 'eq',
            'value': 'security-docs',
            'filter_type': 'native_field'
        },
        {
            'field': 'tags',
            'operator': 'in',
            'value': ['approved', 'current'],
            'filter_type': 'native_field'
        },
        {
            'field': 'status',
            'operator': 'neq',
            'value': 'draft',
            'filter_type': 'custom_metadata'
        }
    ]
})
```

#### Filters with Chat

Focus chat context on specific sources:

```python theme={null}
response = await skald.chat({
    'query': 'What are our security practices?',
    'filters': [
        {
            'field': 'tags',
            'operator': 'in',
            'value': ['security', 'compliance'],
            'filter_type': 'native_field'
        }
    ]
})
```

### Error Handling

```python theme={null}
try:
    result = await skald.create_memo({
        'title': 'My Memo',
        'content': 'Content here'
    })
    print('Success:', result)
except Exception as e:
    print(f'Error: {e}')
```

## Type Hints Support

This package includes full type hints for better IDE support and type checking.

```python theme={null}
from skald_sdk import Skald
from skald_sdk.types import (
    MemoData,
    MemoFileData,
    UpdateMemoData,
    SearchRequest,
    ChatRequest,
    Filter,
    FilterOperator,
    FilterType,
    MemoStatus,
    CreateMemoResponse,
    Memo,
    ListMemosResponse,
    UpdateMemoResponse,
    MemoStatusResponse,
    IdType,
    SearchResponse,
    ChatResponse,
    ChatStreamEvent
)

async def main():
    async with Skald('your-api-key-here') as skald:
        # Create a memo with types
        memo_data: MemoData = {
            'title': 'My Memo',
            'content': 'Content here',
            'tags': ['tag1', 'tag2'],
            'metadata': {'department': 'engineering'}
        }

        create_response: CreateMemoResponse = await skald.create_memo(memo_data)

        # Get memo with types
        memo: Memo = await skald.get_memo('550e8400-e29b-41d4-a716-446655440000')
        memo_by_ref: Memo = await skald.get_memo('external-id-123', 'reference_id')

        # List memos with types
        memos: ListMemosResponse = await skald.list_memos({'page': 1, 'page_size': 20})

        # Update memo with types
        update_data: UpdateMemoData = {
            'title': 'Updated Title',
            'metadata': {'status': 'reviewed'}
        }
        update_response: UpdateMemoResponse = await skald.update_memo(
            '550e8400-e29b-41d4-a716-446655440000',
            update_data
        )

        # Delete memo
        await skald.delete_memo('550e8400-e29b-41d4-a716-446655440000')

        # Upload a file with types
        file_data: MemoFileData = {
            'title': 'Q4 Roadmap',
            'source': 'Product Team',
            'reference_id': 'ROADMAP-Q4-2024',
            'tags': ['roadmap', 'product'],
            'metadata': {'quarter': 'Q4', 'year': '2024'}
        }
        file_response: CreateMemoResponse = await skald.create_memo_from_file(
            '/path/to/document.pdf',
            file_data
        )

        # Check memo status with types
        status: MemoStatusResponse = await skald.check_memo_status(file_response['memo_uuid'])
        memo_status: MemoStatus = status['status']  # "processing", "processed", or "error"

        # Search with filters and types
        filters: list[Filter] = [
            {
                'field': 'source',
                'operator': 'eq',
                'value': 'notion',
                'filter_type': 'native_field'
            },
            {
                'field': 'department',
                'operator': 'eq',
                'value': 'engineering',
                'filter_type': 'custom_metadata'
            }
        ]

        search_request: SearchRequest = {
            'query': 'quarterly goals',
            'limit': 10,
            'filters': filters
        }

        search_response: SearchResponse = await skald.search(search_request)

        # Chat with filters and types
        chat_response: ChatResponse = await skald.chat({
            'query': 'What are our quarterly goals?',
            'filters': filters
        })
        print(chat_response['response'])

        # Streaming chat with types
        async for event in skald.streamed_chat({
            'query': 'What are our quarterly goals?',
            'filters': filters
        }):
            typed_event: ChatStreamEvent = event
            if typed_event['type'] == 'token':
                print(typed_event['content'], end='', flush=True)
```


# Ruby SDK
Source: https://docs.useskald.com/docs/sdks/ruby

Documentation on how to use the Skald Ruby SDK.

Ruby client library for the Skald API.

## Installation

Add this line to your application's Gemfile:

```ruby theme={null}
gem 'skald'
```

And then execute:

```bash theme={null}
bundle install
```

Or install it yourself as:

```bash theme={null}
gem install skald
```

## Requirements

* Ruby 3.0.0 or higher

## Usage

### Initialize the client

```ruby theme={null}
require 'skald'

skald = Skald.new('your-api-key-here')
```

### Memo Management

#### Create a Memo

Create a new memo that will be automatically processed (summarized, tagged, chunked, and indexed for search):

```ruby theme={null}
result = skald.create_memo(
  title: 'Meeting Notes',
  content: 'Full content of the memo...',
  metadata: {
    type: 'notes',
    author: 'John Doe'
  },
  reference_id: 'external-id-123',
  tags: ['meeting', 'q1'],
  source: 'notion',
  expiration_date: '2024-12-31T23:59:59Z'
)

puts result # { ok: true }
```

**Required Fields:**

* `title` (string, max 255 chars) - The title of the memo
* `content` (string) - The full content of the memo

**Optional Fields:**

* `metadata` (hash) - Custom JSON metadata
* `reference_id` (string, max 255 chars) - An ID from your side that you can use to match Skald memo UUIDs with e.g. documents on your end
* `tags` (array of strings) - Tags for categorization
* `source` (string, max 255 chars) - An indication from your side of the source of this content, useful when building integrations
* `expiration_date` (string) - ISO 8601 timestamp for automatic memo expiration

#### Get a Memo

Retrieve a memo by its UUID or your reference ID:

```ruby theme={null}
# Get by UUID
memo = skald.get_memo('550e8400-e29b-41d4-a716-446655440000')

# Get by reference ID
memo = skald.get_memo('external-id-123', 'reference_id')

puts memo[:title]
puts memo[:content]
puts memo[:summary]
puts memo[:tags]
puts memo[:chunks]
```

The `get_memo()` method returns complete memo details including content, AI-generated summary, tags, and content chunks.

#### List Memos

List all memos with pagination:

```ruby theme={null}
# Get first page with default page size (20)
memos = skald.list_memos

# Get specific page with custom page size
memos = skald.list_memos(page: 2, page_size: 50)

puts "Total memos: #{memos[:count]}"
puts "Results: #{memos[:results].length}"
puts "Next page: #{memos[:next]}"
```

**Parameters:**

* `page` (integer, optional) - Page number (default: 1)
* `page_size` (integer, optional) - Results per page (default: 20, max: 100)

#### Update a Memo

Update an existing memo by UUID or reference ID:

```ruby theme={null}
# Update by UUID
skald.update_memo('550e8400-e29b-41d4-a716-446655440000', {
  title: 'Updated Title',
  metadata: { status: 'reviewed' }
})

# Update by reference ID and trigger reprocessing
skald.update_memo('external-id-123', {
  content: 'New content that will be reprocessed'
}, 'reference_id')
```

**Note:** When you update the `content` field, the memo will be automatically reprocessed (summary, tags, and chunks regenerated).

**Updatable Fields:**

* `title` (string)
* `content` (string)
* `metadata` (hash)
* `client_reference_id` (string)
* `source` (string)
* `expiration_date` (string)

#### Delete a Memo

Permanently delete a memo and all associated data:

```ruby theme={null}
# Delete by UUID
skald.delete_memo('550e8400-e29b-41d4-a716-446655440000')

# Delete by reference ID
skald.delete_memo('external-id-123', 'reference_id')
```

**Warning:** This operation permanently deletes the memo and all related data (content, summary, tags, chunks) and cannot be undone.

### Search Memos

Search through your memos using various search methods with optional filters:

```ruby theme={null}
# Basic semantic search
results = skald.search(
  query: 'quarterly goals',
  search_method: 'chunk_vector_search',
  limit: 10
)

# Search with filters
filtered = skald.search(
  query: 'python tutorial',
  search_method: 'title_contains',
  filters: [
    {
      field: 'source',
      operator: 'eq',
      value: 'notion',
      filter_type: 'native_field'
    },
    {
      field: 'level',
      operator: 'eq',
      value: 'beginner',
      filter_type: 'custom_metadata'
    }
  ]
)

puts "Found #{filtered[:results].length} results"
filtered[:results].each do |memo|
  puts "- #{memo[:title]} (distance: #{memo[:distance]})"
end
```

#### Search Methods

* **`chunk_vector_search`** - Semantic search on memo chunks for detailed content search
* **`title_contains`** - Case-insensitive substring match on memo titles
* **`title_startswith`** - Case-insensitive prefix match on memo titles

#### Search Parameters

* `query` (string, required) - The search query
* `search_method` (SearchMethod, required) - One of the search methods above
* `limit` (integer, optional) - Maximum results to return (1-50, default 10)
* `filters` (array, optional) - Array of filter hashes to narrow results (see Filters section below)

#### Search Response

```ruby theme={null}
{
  results: [
    {
      uuid: "550e8400-...",
      title: "Project Planning Meeting",
      summary: "Discussed Q1 goals...",
      content_snippet: "...relevant excerpt from the content...",
      distance: 0.45  # For vector search: 0-2, lower is better. nil for title searches
    }
  ]
}
```

* `uuid` - Unique identifier for the memo
* `title` - Memo title
* `summary` - Auto-generated summary for the memo
* `content_snippet` - A snippet containing the beginning of the memo
* `distance` - A decimal from 0 to 2 determining how close the result was deemed to be to the query when using semantic search (`chunk_vector_search`). The closer to 0 the more related the content is to the query. `nil` if using `title_contains` or `title_startswith`.

### Chat with Your Knowledge Base

Ask questions about your memos using an AI agent. The agent retrieves relevant context and generates answers with inline citations.

#### Non-Streaming Chat

```ruby theme={null}
result = skald.chat(
  query: 'What were the main points discussed in the Q1 meeting?'
)

puts result[:response]
# "The main points discussed in the Q1 meeting were:
# 1. Revenue targets    
# 2. Hiring plans
# 3. Product roadmap"

puts result[:ok] # true
```

#### Streaming Chat

For real-time responses, use streaming chat:

```ruby theme={null}
skald.streamed_chat(
  query: 'What are our quarterly goals?'
).each do |event|
  if event[:type] == 'token'
    # Write each token as it arrives
    print event[:content]
  elsif event[:type] == 'done'
    puts "\nDone!"
  end
end
```

#### Chat Parameters

* `query` (string, required) - The question to ask
* `filters` (array, optional) - Array of filter hashes to focus chat context on specific sources (see Filters section below)

#### Chat Response

Non-streaming responses include:

* `ok` (boolean) - Success status
* `response` (string) - The AI's answer
* `intermediate_steps` (array) - Steps taken by the agent (for debugging)

Streaming responses yield events:

* `{ type: 'token', content: string }` - Each text token as it's generated
* `{ type: 'done' }` - Indicates the stream has finished

### Generate Documents

Generate documents based on prompts and retrieved context from your knowledge base. Similar to chat but optimized for document generation with optional style/format rules.

#### Non-Streaming Document Generation

```ruby theme={null}
result = skald.generate_doc(
  prompt: 'Create a product requirements document for a new mobile app',
  rules: 'Use formal business language. Include sections for: Overview, Requirements, Technical Specifications, Timeline'
)

puts result[:response]
# "# Product Requirements Document
#
# ## Overview
# This document outlines the requirements for...
#
# ## Requirements
# 1. User authentication
# 2. Push notifications..."

puts result[:ok] # true
```

#### Streaming Document Generation

For real-time document generation, use streaming:

```ruby theme={null}
skald.streamed_generate_doc(
  prompt: 'Write a technical specification for user authentication',
  rules: 'Include sections for: Architecture, Security, API Endpoints, Data Models'
).each do |event|
  if event[:type] == 'token'
    # Write each token as it arrives
    print event[:content]
  elsif event[:type] == 'done'
    puts "\nDone!"
  end
end
```

#### Generate Document Parameters

* `prompt` (string, required) - The prompt describing what document to generate
* `rules` (string, optional) - Optional style/format rules (e.g., "Use formal language. Include sections: X, Y, Z")
* `filters` (array, optional) - Array of filter hashes to control which memos are used for generation (see Filters section below)

#### Generate Document Response

Non-streaming responses include:

* `ok` (boolean) - Success status
* `response` (string) - The generated document
* `intermediate_steps` (array) - Steps taken by the agent (for debugging)

Streaming responses yield events:

* `{ type: 'token', content: string }` - Each text token as it's generated
* `{ type: 'done' }` - Indicates the stream has finished

### Filters

Filters allow you to narrow down results based on memo metadata. You can filter by native fields or custom metadata fields. Filters are supported in `search()`, `chat()`, `generate_doc()`, and their streaming variants.

See [Filters](/docs/api-reference/filters) for complete documentation.

#### Filter Structure

```ruby theme={null}
{
  field: "field_name",          # Field name to filter on
  operator: "eq",               # Comparison operator
  value: "value",               # Value(s) to compare against
  filter_type: "native_field"   # 'native_field' or 'custom_metadata'
}
```

#### Native Fields

Native fields are built-in memo properties:

* `title` - Memo title
* `source` - Source system (e.g., "notion", "confluence")
* `client_reference_id` - Your external reference ID
* `tags` - Memo tags (array)

#### Custom Metadata Fields

You can filter on any field from the `metadata` hash you provided when creating the memo.

#### Filter Operators

* **`eq`** - Equals (exact match)
* **`neq`** - Not equals
* **`contains`** - Contains substring (case-insensitive)
* **`startswith`** - Starts with prefix (case-insensitive)
* **`endswith`** - Ends with suffix (case-insensitive)
* **`in`** - Value is in array (requires array value)
* **`not_in`** - Value is not in array (requires array value)

#### Filter Examples

```ruby theme={null}
# Filter by source
{
  field: 'source',
  operator: 'eq',
  value: 'notion',
  filter_type: 'native_field'
}

# Filter by multiple tags
{
  field: 'tags',
  operator: 'in',
  value: ['security', 'compliance'],
  filter_type: 'native_field'
}

# Filter by title containing text
{
  field: 'title',
  operator: 'contains',
  value: 'meeting',
  filter_type: 'native_field'
}

# Filter by custom metadata field
{
  field: 'department',
  operator: 'eq',
  value: 'engineering',
  filter_type: 'custom_metadata'
}

# Exclude specific sources
{
  field: 'source',
  operator: 'not_in',
  value: ['draft', 'archive'],
  filter_type: 'native_field'
}
```

#### Combining Multiple Filters

When you provide multiple filters, they are combined with AND logic (all filters must match):

```ruby theme={null}
results = skald.search(
  query: 'security best practices',
  search_method: 'chunk_vector_search',
  filters: [
    {
      field: 'source',
      operator: 'eq',
      value: 'security-docs',
      filter_type: 'native_field'
    },
    {
      field: 'tags',
      operator: 'in',
      value: ['approved', 'current'],
      filter_type: 'native_field'
    },
    {
      field: 'status',
      operator: 'neq',
      value: 'draft',
      filter_type: 'custom_metadata'
    }
  ]
)
```

#### Filters with Chat

Focus chat context on specific sources:

```ruby theme={null}
result = skald.chat(
  query: 'What are our security practices?',
  filters: [
    {
      field: 'tags',
      operator: 'in',
      value: ['security', 'compliance'],
      filter_type: 'native_field'
    }
  ]
)
```

#### Filters with Document Generation

Control which memos are used for document generation:

```ruby theme={null}
doc = skald.generate_doc(
  prompt: 'Create an API integration guide',
  rules: 'Use technical language with code examples',
  filters: [
    {
      field: 'source',
      operator: 'in',
      value: ['api-docs', 'technical-specs'],
      filter_type: 'native_field'
    },
    {
      field: 'document_type',
      operator: 'eq',
      value: 'specification',
      filter_type: 'custom_metadata'
    }
  ]
)
```

### Error Handling

```ruby theme={null}
begin
  result = skald.create_memo(
    title: 'My Memo',
    content: 'Content here'
  )
  puts "Success: #{result}"
rescue => e
  puts "Error: #{e.message}"
end
```


# No third-party services
Source: https://docs.useskald.com/docs/self-host/full-local

Instructions on how to deploy Skald without sending your data anywhere outside of your infrastructure. Experimental.

We understand that there are use cases that require that no data be sent out to third-party services, including LLM providers like OpenAI.

For this reason, we've set up Skald so that it can be deployed without connecting to any third-party provider at all, giving you full control over your data.

As we're new to the self-hosted LLM space, we've done the ground work to make this happen, but we understand that to make this work well there's more that needs to be done. If you're knowledgeable about this, don't hesitate to reach out or even submit a PR on our [repo](https://github.com/skaldlabs/skald).

We've tested and ensured that the setup outlined here works, but it's certainly limited.

## Pre-requisites

* Have a running LLM inference server with an OpenAI-compatible API e.g. Ollama, llama.cpp (we've explicitly tested with llama.cpp)

## Setup

We've built Skald to work on top of as much open-source infrastructure as possible, so we use Postgres with `pgvector` for our main DB and vector DB.

That means the only parts of the core stack that need to be adapted to work with a fully "local" setup are the LLM, the embeddings setup, and the document extraction pipeline.

On our Cloud deployment, we support OpenAI, Anthropic, and Groq as the LLM providers, use Voyage AI for vector embeddings, and Datalab for document extraction.

As a result, we need substitutes for all three of those when self-hosting in a fully local setup.

### Embeddings

Our `docker-compose.yml` comes configured with an optional `embedding-service` component that's attached to the `local-embedding` profile. This service uses the Python package [`sentence-transformers`](https://pypi.org/project/sentence-transformers/) to expose an `/embed` and a `/rerank` endpoint that our other services can use to generate vector embeddings and rerank results without sending data elsewhere.

In order to use it, you should set the env var `EMBEDDING_PROVIDER=local` and run the stack with `docker-compose --profile local-embedding up`. This should then just work out of the box.

### LLM

For the LLM configuration, you'll need to have a running LLM inference server yourself. This server should have an OpenAI compatible API and support tool-calling.

We've tested this using `llama.cpp` but equivalent providers should also work.

Once you have this running, you can then set `LLM_PROVIDER=local` and `LOCAL_LLM_BASE_URL` to your server's endpoint.

As of today, the only configuration we support is the URL, meaning this is best suited for a server running on the same machine for security reasons. We intend to expand this to include support for security-related variables that would make it viable to run the LLM server on another machine, and we'd be keen to hear from people who are deploying open-source models how you've been securing these servers.

### Document extraction (optional)

Skald does not require a document extraction setup to work and you can skip this if you'll be dealing exclusively with plaintext.

But if you want to use document extraction features, you need to set appropriate environment variables for connecting to S3 or an S3-compatible object storage service. This is where documents will be stored.

```sh theme={null}
AWS_REGION=<your_s3_region>
AWS_ACCESS_KEY_ID=<your_aws_access_key_id>
AWS_SECRET_ACCESS_KEY=<your_aws_secret_access_key>
S3_BUCKET_NAME=<your_s3_bucket>
```

Then for the document extraction itself you should run the stack with the `local` profile. This will spin up a local [Docling](https://www.docling.ai/) server and configure the appropriate environment variables for it.

### Postgres

By default we will spin up a Postgres instance as part of the Docker Compose stack for you, and we will install `pgvector` on it. If you're running a production deploy you would ideally host and manage Postgres yourself. If you do so, you just need to set the `DATABASE_URL` env var to point to your instance, and run the stack without starting the Postgres service.

<Note>If you do host Postgres elsewhere, the one thing you need to remember is to install the `pgvector` extension on the instance.</Note>

### RabbitMQ

The same concepts that apply to Postgres apply to RabbitMQ. Ideally you'd host this yourself in a prod deployment, and for that you should spin up the stack without the RabbitMQ service and set the following vars:

```sh theme={null}
RABBITMQ_HOST
RABBITMQ_PORT
RABBITMQ_USER
RABBITMQ_PASSWORD
RABBITMQ_VHOST
```


# Self-hosting Skald
Source: https://docs.useskald.com/docs/self-host/intro

Documentation on how to self-host Skald

<Note>
  We've spent a lot of effort making Skald easy to self-host, but we're still very early. New features are being added multiple times a day and our documentation can't always keep up. We also don't have a self-hosted release schedule yet, and all changes are just automatically available.

  If you're interested in self-hosting, we **highly recommend you talk to us [on Slack](https://join.slack.com/t/skaldcommunity/shared_invite/zt-3he986lub-UWKTZneOAUeTFa4LDXpFEg)** so we can help you out and work together to get you a solid Skald deployment. We're happy to help as much as possible.
</Note>

Skald is licensed under the MIT license and we provide a standard Docker Compose deployment if you want to self-host.

The self-hosted deployment has all the features of our Cloud version, except for the fact that it is single-tenant, meaning you can only create one organization per instance (you can create unlimited projects, however).

## Deployment types

The only supported way to deploy Skald today is with Docker Compose, but we have separate instructions depending on the type of deploy you want to do. Refer to the links below depending on your use case:

1. Local testing: use the Quickstart setup below
2. [Production self-hosted deploy](/docs/self-host/production)
3. [Deployment with no third-party services (experimental)](/docs/self-host/full-local)

## Quickstart

The best way to try out the Skald self-hosted version is the following:

```sh theme={null}
git clone https://github.com/skaldlabs/skald
cd skald
echo "OPENAI_API_KEY=<your_key>" > .env
docker-compose up
```

The UI will be available at `http://localhost:3000` and the API at `http://localhost:8000`.

This setup will get you started quickly while only requiring one API key for an external service. We'll spin up and configure all other services for you, including RabbitMQ and Postgres.

The one caveat of this deploy is that it relies entirely on OpenAI for the whole stack, which makes for a slightly slower API. The reason for this is that OpenAI doesn't provide a reranking API, so we use a slower mechanism that uses LLM calls to rerank chunks. If you don't understand what this means, that's ok -- you don't have to. But just know that your API will be slower if you use OpenAI exclusively.

In our Cloud version, we use [Voyage AI](https://www.voyageai.com/) for both embeddings and reranking, and that's what we recommend you do as well for the best performance (reranking is faster and better and the embedding models are arguably better too). That means also setting `VOYAGE_API_KEY=<your_key>` and `EMBEDDING_PROVIDER=voyage` (this will also apply to re-ranking).

## Configuration

### LLM

You can configure Skald to use multiple LLM providers, but you still need to set an `LLM_PROVIDER` environment variable. This is likely to change in the future, or transform into `DEFAULT_LLM_PROVIDER` but as of today, the provider defined by this env var will be used for:

* Chat responses as the default provider if not overridden in the `rag_config`
* Extracting the summary and tags for new memos
* LLM-as-a-Judge feature in Experiments

If you set additional environment variables for providers that are not your `LLM_PROVIDER`, those will be available for use in chat.

```sh theme={null}
# default: openai
LLM_PROVIDER=<openai|anthropic|groq|local>

# if you selected openai
OPENAI_API_KEY=<your_openai_key>

# if you selected anthropic
ANTHROPIC_API_KEY=<your_anthropic_key>

# if you selected groq
GROQ_API_KEY=<your_groq_key>

# if you selected local
LOCAL_LLM_BASE_URL=<url_of_self_hosted_llm_server>
LOCAL_LLM_MODEL=<model_name> # e.g. llama-3.1-8b-instruct
```

The OpenAI, Anthropic, and Groq keys are self-explanatory, and if you're interested in the local LLM setup, please refer to the [docs for a deployment with no third-party services](/docs/self-host/full-local).

### Embeddings

Configuration for embeddings works similarly to the LLM config, with the following vars:

```sh theme={null}
# default: openai
EMBEDDING_PROVIDER=<openai|voyage|local>

# if you selected openai
OPENAI_API_KEY=<your_openai_key>

# if you selected voyage
VOYAGE_API_KEY=<your_voyageai_key>
```

Note that while the default provider is set to `openai`, **we actually recommend using `voyage`.** The reason this is not the default is simply because most people already have an OpenAI account these days, while VoyageAI is not used as widely. However, we use Voyage on our Cloud deployment and strongly recommend it -- the embedding models are great.

The additional benefit of using Voyage embeddings is that you also will get the Voyage re-ranker, which is both really good and really fast. We currently don't support configuring a re-ranker separately to the embedding provider but may do so in the future.

<Warning>Changing the embedding provider on a running deployment is not currently supported and will invalidate all memos ingested up until the change was made. If you do this, you should delete all existing memos from the database and re-process them.</Warning>

### Document extraction

If you want to use document extraction features, you need to set appropriate environment variables for connecting to S3 or an S3-compatible object storage service. This is where documents will be stored.

```sh theme={null}
AWS_REGION=<your_s3_region>
AWS_ACCESS_KEY_ID=<your_aws_access_key_id>
AWS_SECRET_ACCESS_KEY=<your_aws_secret_access_key>
S3_BUCKET_NAME=<your_s3_bucket>
```

For the document extraction itself, you have two options:

1. You can set `DATALAB_API_KEY` (from [https://datalab.to](https://datalab.to))
2. You can set `DOCUMENT_EXTRACTION_PROVIDER=docling` and run the stack with the `local` profile. This will spin up a local [Docling](https://www.docling.ai/) server that works very well for document extraction, but not as well as Datalab. Docling is MIT-licensed though, and will be running on your own infrastructure.

### Postgres

By default we will spin up a Postgres instance as part of the Docker Compose stack for you, and we will install `pgvector` on it. If you're running a production deploy you would ideally host and manage Postgres yourself. If you do so, you just need to set the `DATABASE_URL` env var to point to your instance, and run the stack without starting the Postgres service.

<Note>If you do host Postgres elsewhere, the one thing you need to remember is to install the `pgvector` extension on the instance.</Note>

### RabbitMQ

The same concepts that apply to Postgres apply to RabbitMQ. Ideally you'd host this yourself in a prod deployment, and for that you should spin up the stack without the RabbitMQ service and set the following vars:

```sh theme={null}
RABBITMQ_HOST
RABBITMQ_PORT
RABBITMQ_USER
RABBITMQ_PASSWORD
RABBITMQ_VHOST
```

## Help this isn't working

We're early and so you may encounter quirks when deploying Skald! If that happens, please [submit an issue](https://github.com/skaldlabs/skald/issues/new) and we'll be happy to help you. Even better if you want to submit a PR.


# Production self-hosted deployment
Source: https://docs.useskald.com/docs/self-host/production

How to deploy and manage a Skald instance for production workflows

This guide will help you deploy a production-ready Skald instance on your own infrastructure.

Spinning up the complete stack so that you have Skald live on domains that you own with SSL certificates should realistically take only 20-30min, but that's with Postgres and RabbitMQ running in Docker. These should ideally be deployed externally and of course configuring those will take more time.

### Pre-requisites

1. A Linux server (x86) with [Docker](https://docs.docker.com/engine/install/ubuntu/) and [Docker Compose](https://docs.docker.com/compose/install/linux/) installed
2. Two domain names (or subdomains) pointing to your server's IP address:
   * One for the API (e.g., `api.yourdomain.com`)
   * One for the UI (e.g., `app.yourdomain.com`)
3. Ports 80 and 443 open on your server

<Info>The last step is easy to forget! Do it right when you spin up your instance to prevent yourself from spending time debugging later.</Info>

### DNS Configuration

Before running the deployment, ensure the following DNS records are configured:

1. Create an A record for your API domain pointing to your server's IP address
2. Create an A record for your UI domain pointing to your server's IP address

Example DNS configuration:

```
skald-api.yourdomain.com    A    123.456.789.0
skald.yourdomain.com        A    123.456.789.0
```

<Tip>If you are using CloudFlare to manage your DNS, make sure to **disable the 'Proxied'** option. A proxied record will not work with our Traefik configuration.</Tip>

### Deployment

Clone the Skald repo:

```bash theme={null}
git clone https://github.com/skaldlabs/skald
```

And then from inside the directory, run the deployment setup script:

```bash theme={null}
./bin/deploy.sh
```

The script will:

1. Prompt you for your API and UI domain names.
2. Request an email address (required for Let's Encrypt SSL certificates).
3. Prompt you for the environment variables required to run Skald (e.g. API keys). Check out the [Configuration](/docs/self-host/intro#configuration) section on the Intro page if you want to understand these better.
4. Verify your DNS configuration.
5. Generate secure credentials (e.g. Django's SECRET\_KEY, Postgres password).
6. Set up a .env.prod file to be used when deploying the stack.

After you're done with the setup, run the following command to start the stack in detached mode:

```sh theme={null}
docker compose -f docker-compose.selfhosted.yml --env-file .env.prod up -d
```

### Managing Your Deployment

#### View logs

```bash theme={null}
docker compose -f docker-compose.selfhosted.yml logs -f
```

View logs for a specific service:

```bash theme={null}
docker compose -f docker-compose.selfhosted.yml logs -f api
```

#### Stop the deployment

```bash theme={null}
docker compose -f docker-compose.selfhosted.yml down
```

#### Restart the deployment

```bash theme={null}
docker compose -f docker-compose.selfhosted.yml --env-file .env.prod up -d
```

#### Update the deployment

To update to the latest version:

```bash theme={null}
# Pull the latest images from DockerHub
docker compose -f docker-compose.selfhosted.yml --env-file .env.prod pull

# Restart services with the new images
docker compose -f docker-compose.selfhosted.yml --env-file .env.prod up -d
```

### What Gets Deployed

The deployment includes:

* **Traefik**: Reverse proxy with automatic SSL certificate generation.
* **PostgreSQL with pgvector**: Our database. `pgvector` support is needed for vector embeddings.
* **RabbitMQ**: Used for communicating between the Django server and the Memo Processing Server.
* **API**: The main Skald API Django server.
* **Memo Processing Server**: Background worker for processing memos.
* **UI**: The web interface.

### Configuration

All configuration is stored in `.env.prod`, which is automatically generated by the deployment script. This file contains:

* Domain names
* Database credentials
* API keys
* Security secrets

### SSL Certificates

SSL certificates are automatically generated and renewed by Let's Encrypt through Traefik. The certificates are stored in a Docker volume (`traefik-certificates`) and will auto-renew before expiration.

### Troubleshooting

#### SSL certificate issues

If you're having trouble with SSL certificates:

1. Ensure ports 80 and 443 are open
2. Verify DNS records are pointing to the correct IP
3. Check Traefik logs: `docker compose -f docker-compose.selfhosted.yml logs traefik`
4. Wait a few minutes -- certificate generation can take some time

#### Service won't start

1. Check service logs: `docker compose -f docker-compose.selfhosted.yml logs <service-name>`
2. Ensure all required environment variables are set in `.env.prod`

#### Cannot connect to API

1. Verify DNS is resolving correctly: `dig your-api-domain.com`
2. Check API logs: `docker compose -f docker-compose.selfhosted.yml logs api`
3. Ensure Traefik is running: `docker compose -f docker-compose.selfhosted.yml ps traefik`

### Backups

To backup your data (if you're not using an external Postgres deployment), you can run the following command (or set it to run on a cron):

```bash theme={null}
docker run --rm -v skald2_postgres_data:/data -v $(pwd):/backup ubuntu tar czf /backup/postgres-backup.tar.gz /data
```

To restore:

```bash theme={null}
docker run --rm -v skald2_postgres_data:/data -v $(pwd):/backup ubuntu tar xzf /backup/postgres-backup.tar.gz -C /
```