Python SDK

Python client library for the Skald API.

Installation

pip install skald-sdk

Requirements

Python 3.8 or higher

Usage

Initialize the client

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

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)  # { '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 (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:

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

List Memos

List all memos with pagination:

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

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

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

Search Memos

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

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

# Search with filters
filtered = await 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'
        }
    ]
})

print(f"Found {len(filtered['results'])} results")
for memo in filtered['results']:
    print(f"- {memo['title']} (distance: {memo['distance']})")

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 (list, optional) - List of filter objects to narrow results (see Filters section below)

Search Response

{
    'results': [
        {
            'uuid': str,
            'title': str,
            'summary': str,
            'content_snippet': str,
            'distance': float | None
        }
    ]
}

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

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

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

print(result['ok'])  # True

Streaming Chat

For real-time responses, use streaming chat:

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 (string) - The AI’s answer with inline citations in format [[N]]
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

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

result = await 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'
})

print(result['response'])
# "# Product Requirements Document
#
# ## Overview
# This document outlines the requirements for...
#
# ## Requirements
# 1. User authentication [[1]]
# 2. Push notifications [[2]]..."

print(result['ok'])  # True

Streaming Document Generation

For real-time document generation, use streaming:

async for event in skald.streamed_generate_doc({
    'prompt': 'Write a technical specification for user authentication',
    'rules': 'Include sections for: Architecture, Security, API Endpoints, Data Models'
}):
    if event['type'] == 'token':
        # Print each token as it arrives
        print(event['content'], end='', flush=True)
    elif event['type'] == 'done':
        print('\nDone!')

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 (list, optional) - List of filter objects to control which memos are used for generation (see Filters section below)

Generate Document Response

Non-streaming responses include:

ok (bool) - Success status
response (string) - The generated document with inline citations in format [[N]]
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(), generate_doc(), and their streaming variants. See Filters for complete documentation.

Filter Structure

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

# 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):

results = await 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:

result = await 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:

doc = await 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

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.

from skald_sdk import Skald
from skald_sdk.types import (
    MemoData,
    UpdateMemoData,
    SearchRequest,
    ChatRequest,
    Filter,
    SearchMethod,
    FilterOperator,
    FilterType,
    CreateMemoResponse,
    Memo,
    ListMemosResponse,
    UpdateMemoResponse,
    IdType,
    SearchResponse,
    ChatResponse,
    ChatStreamEvent,
    GenerateDocRequest,
    GenerateDocResponse,
    GenerateDocStreamEvent
)

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

        # 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',
            'search_method': 'chunk_vector_search',
            '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
        })

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

        # Generate document with filters and types
        generate_doc_response: GenerateDocResponse = await skald.generate_doc({
            'prompt': 'Create a product requirements document for a new mobile app',
            'rules': 'Use formal business language. Include sections for: Overview, Requirements',
            'filters': filters
        })

        # Streaming document generation with types
        async for event in skald.streamed_generate_doc({
            'prompt': 'Write a technical specification',
            'rules': 'Include Architecture and Security sections',
            'filters': filters
        }):
            typed_event: GenerateDocStreamEvent = event
            if typed_event['type'] == 'token':
                print(typed_event['content'], end='', flush=True)
            elif typed_event['type'] == 'done':
                print('\nDone!')

Getting started

Self-host

SDKs

API Reference

Installation

Requirements

Usage

Initialize the client

Memo Management

Create a Memo

Get a Memo

List Memos

Update a Memo

Delete a Memo

Search Memos

Search Methods

Search Parameters

Search Response

Chat with Your Knowledge Base

Non-Streaming Chat

Streaming Chat

Chat Parameters

Chat Response

Generate Documents

Non-Streaming Document Generation

Streaming Document Generation

Generate Document Parameters

Generate Document Response

Filters

Filter Structure

Native Fields

Custom Metadata Fields

Filter Operators

Filter Examples

Combining Multiple Filters

Filters with Chat

Filters with Document Generation

Error Handling

Type Hints Support

Getting started

Self-host

SDKs

API Reference

​Installation

​Requirements

​Usage

​Initialize the client

​Memo Management

​Create a Memo

​Get a Memo

​List Memos

​Update a Memo

​Delete a Memo

​Search Memos

​Search Methods

​Search Parameters

​Search Response

​Chat with Your Knowledge Base

​Non-Streaming Chat

​Streaming Chat

​Chat Parameters

​Chat Response

​Generate Documents

​Non-Streaming Document Generation

​Streaming Document Generation

​Generate Document Parameters

​Generate Document Response

​Filters

​Filter Structure

​Native Fields

​Custom Metadata Fields

​Filter Operators

​Filter Examples

​Combining Multiple Filters

​Filters with Chat

​Filters with Document Generation

​Error Handling

​Type Hints Support

Installation

Requirements

Usage

Initialize the client

Memo Management

Create a Memo

Get a Memo

List Memos

Update a Memo

Delete a Memo

Search Memos

Search Methods

Search Parameters

Search Response

Chat with Your Knowledge Base

Non-Streaming Chat

Streaming Chat

Chat Parameters

Chat Response

Generate Documents

Non-Streaming Document Generation

Streaming Document Generation

Generate Document Parameters

Generate Document Response

Filters

Filter Structure

Native Fields

Custom Metadata Fields

Filter Operators

Filter Examples

Combining Multiple Filters

Filters with Chat

Filters with Document Generation

Error Handling

Type Hints Support