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

# PHP SDK

> 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