===============
LIBRARY RULES
===============
From library maintainers:
- Read docs/http-contract.md for the maintained HTTP response contract and docs/client.md for SDK signatures. Completed job content is a segment array and requestId is required. A completed status without content can mean the stored result expired.
- For LangChain, install capslane[langchain]>=0.2.0 and import CapslaneLoader from capslane.langchain. It defaults to native and preserves timestamp citations. Read docs/langchain.md for local chunking, job_id recovery and the keyword retrieval example.
- Only transcript url is required. mode is optional, accepts native, auto or generate, and defaults to auto. The content value is a list of segment dictionaries by default and a string only for an immediate text=True result.
- Install capslane and import CapslaneClient and CapslaneError from capslane. Keep CAPSLANE_API_KEY in the server environment, outside prompts and source control. Python 3.10 or later is required.
- Check for content before jobId. A completed job contains both. Use wait_for_transcript for accepted jobs and preserve their ID so polling can resume without another submission.
- Cache lookup happens before mode selection. On a cache miss, native never starts generation; auto falls back only after confirmed missing captions. Inspect source and cached in every result.
- Use transcript_job to check an existing job once. HTTP 200 does not mean the job is complete; stop on failed or cancelled. Bound network calls and the polling window separately with their timeout arguments.
- Completed jobs return canonical timestamped segments. text and chunk_size affect immediate results only. Join segment text locally when plain text is required after polling.
- Segment offset and duration values are milliseconds. lang is a preferred caption language, not a translation request.
- A transcript submission reserves a monthly unit before cache lookup. Cache hits and later failures can consume it. Polling an existing job does not reserve another transcript unit.
- Read CapslaneError.code before retrying. Use bounded backoff for temporary failures. Monthly allowance errors need a reset or allowance change. Client cancellation does not cancel an accepted server job.
- wait_for_transcript(job, *, interval=2.0, timeout=1200) uses seconds. timeout=None is unsupported. The client network timeout defaults to 20 seconds. A valid unknown job returns job_not_found; local polling expiry uses processing_timeout.

### GET /v1/account response

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Example JSON response for GET /v1/account. Returns workspace, plan, and monthlyLimit. Reserves no transcript unit.

```json
{
  "workspace": "Fixture",
  "plan": "free",
  "monthlyLimit": 50
}
```

--------------------------------

### Install the Capslane SDK

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Install the base package using pip. This package requires Python 3.10 or later.

```bash
python -m pip install capslane
```

--------------------------------

### Load YouTube transcripts with CapslaneLoader

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/langchain.md

Example script to load a YouTube transcript using CapslaneLoader. Save as langchain_quickstart.py and run with python.

```python
import json
import sys

from capslane import CapslaneError
from capslane.langchain import CapslaneLoader

loader = CapslaneLoader("dQw4w9WgXcQ", lang="en", chunk_size=1000)

try:
    for document in loader.lazy_load():
        print(json.dumps(document.model_dump(), ensure_ascii=False))
except CapslaneError as error:
    print(error.code, error.request_id, "job:", loader.job_id, file=sys.stderr)
    raise
```

--------------------------------

### Install Capslane LangChain package

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Install the required package version to enable LangChain support.

```sh
python -m pip install "capslane[langchain]==0.2.0"
```

--------------------------------

### Retrieve a YouTube transcript with CapslaneClient

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

This example demonstrates how to initialize the client and fetch a transcript for a video. It handles both immediate results and asynchronous generation jobs using the auto mode.

```python
import json
import os
import sys

from capslane import CapslaneClient, CapslaneError

client = CapslaneClient(api_key=os.environ["CAPSLANE_API_KEY"], timeout=45)

try:
    result = client.transcript("dQw4w9WgXcQ", mode="auto")
    if "content" not in result:
        print("Accepted job:", result["jobId"], file=sys.stderr)
        result = client.wait_for_transcript(result, timeout=20 * 60)
    print(json.dumps(result, indent=2))
except CapslaneError as error:
    print(error.code, error.status, error.request_id, file=sys.stderr)
    raise
```

--------------------------------

### GET /v1/transcript immediate response

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Example JSON response for a successful immediate transcript request. content is an array of segments by default, each with text, offset, duration, and lang.

```json
{
  "content": [{ "text": "Synthetic fixture.", "offset": 1000, "duration": 2000, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "generated",
  "cached": true,
  "requestId": "req_example"
}
```

--------------------------------

### GET /v1/account

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Retrieves account information including workspace, plan, and monthly limit. This endpoint does not reserve a transcript unit.

```APIDOC
## GET /v1/account

### Description
Retrieves account information including workspace, plan, and monthly limit. This endpoint does not reserve a transcript unit.

### Method
GET

### Endpoint
/v1/account

### Response
#### Success Response (200)
- **workspace** (string) - The workspace name.
- **plan** (string) - The plan type (e.g., free).
- **monthlyLimit** (integer) - The monthly transcript limit.

#### Response Example
{
  "workspace": "Fixture",
  "plan": "free",
  "monthlyLimit": 50
}
```

--------------------------------

### Convert Capslane result to plain text

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Use this snippet after the quickstart to extract plain text from the result content, handling both string and segment list formats.

```python
content = result["content"]
plain = content if isinstance(content, str) else " ".join(segment["text"] for segment in content)
```

--------------------------------

### GET /v1/transcript

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Returns an immediate transcript for a public YouTube URL or video ID. Supports optional parameters for mode, language, text format, and chunk size.

```APIDOC
## GET /v1/transcript

### Description
Returns an immediate transcript for a public YouTube URL or video ID. Supports optional parameters for mode, language, text format, and chunk size.

### Method
GET

### Endpoint
/v1/transcript

### Parameters
#### Query Parameters
- **url** (string) - Required - A public YouTube URL or an 11-character video ID.
- **mode** (string) - Optional - Defaults to auto. Accepts native, auto, or generate.
- **lang** (string) - Optional - Preferred caption language. Does not request translation.
- **text** (boolean) - Optional - Defaults to false. If true, content is a string instead of an array.
- **chunkSize** (integer) - Optional - Groups whole segments with a character budget from 50 to 10,000. Ignored when text=true.

### Response
#### Success Response (200)
- **content** (array or string) - Array of segments by default, or string when text=true. Each segment has text, offset, duration, and lang.
- **lang** (string) - The language of the transcript.
- **availableLangs** (array of strings) - Available languages.
- **source** (string) - Source of the transcript (e.g., generated).
- **cached** (boolean) - Whether the response was cached.
- **requestId** (string) - Unique request identifier.

#### Response Example
{
  "content": [{ "text": "Synthetic fixture.", "offset": 1000, "duration": 2000, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "generated",
  "cached": true,
  "requestId": "req_example"
}
```

--------------------------------

### Initialize CapslaneLoader and load documents

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Initialize the loader with a video ID and language, then iterate through the loaded LangChain documents.

```python
from capslane.langchain import CapslaneLoader

loader = CapslaneLoader("dQw4w9WgXcQ", lang="en", chunk_size=1000)
documents = loader.load()
for document in documents:
    print(document.metadata["source"], document.page_content)
```

--------------------------------

### Initialize CapslaneClient

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Constructs the client instance. The api_key is mandatory, while base_url and timeout are optional.

```python
CapslaneClient(api_key: str, base_url: str = "https://capslane.com", timeout: float = 20.0)
```

--------------------------------

### Run search_transcript.py for keyword retrieval

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/langchain.md

Executes the search_transcript.py script to load a transcript and retrieve up to three chunks matching the query. This performs keyword retrieval and returns JSON output with text and source metadata.

```sh
python search_transcript.py "dQw4w9WgXcQ" --lang en --query "give up"
```

--------------------------------

### CapslaneClient Constructor

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Initializes a new Capslane client instance. The constructor does not perform network calls.

```APIDOC
## CapslaneClient(api_key: str, base_url: str = "https://capslane.com", timeout: float = 20.0)

### Description
Initializes the client with your workspace API key. The base_url and timeout parameters are optional.

### Parameters
- **api_key** (str) - Required - Your workspace API key.
- **base_url** (str) - Optional - The base URL for the API. Defaults to https://capslane.com.
- **timeout** (float) - Optional - Request timeout in seconds. Defaults to 20.0.
```

--------------------------------

### client.transcript(url, *, lang=None, text=None, chunk_size=None, mode=None)

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Initiates a transcription request for a given URL. Only the URL is required, while other parameters are optional and keyword-only.

```APIDOC
## client.transcript(url, *, lang=None, text=None, chunk_size=None, mode=None)

### Description
Initiates a transcription request. Returns a dictionary containing either the 'content' or a 'jobId'.

### Parameters
- **url** (string) - Required - The URL of the media to transcribe.
- **lang** (string) - Optional - Language code.
- **text** (boolean) - Optional - If true, returns text instead of segments.
- **chunk_size** (integer) - Optional - Size of chunks.
- **mode** (string) - Optional - Processing mode: 'native', 'auto', or 'generate'.

### Response
- **content** (list/string) - The transcription result.
- **jobId** (string) - The ID of the job if not immediately available.
- **lang** (string) - Detected language.
- **availableLangs** (list) - List of available languages.
- **source** (string) - Processing source.
- **cached** (boolean) - Whether the result was cached.
- **requestId** (string) - Unique request identifier.
```

--------------------------------

### Submit a transcript

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Submits a URL for transcription. Only the url parameter is required; other parameters are keyword-only.

```python
client.transcript(url, *, lang=None, text=None, chunk_size=None, mode=None)
```

--------------------------------

### Resume and wait for a transcript job

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Checks the status of an existing job using CAPSLANE_JOB_ID and waits for completion if the content is not yet available.

```python
result = client.transcript_job(os.environ["CAPSLANE_JOB_ID"])
transcript = result if "content" in result else client.wait_for_transcript(result, timeout=20 * 60)
```

--------------------------------

### client.transcript

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Submits a URL for transcription. This method returns a dictionary containing either the transcript content or a job ID for polling.

```APIDOC
## client.transcript(url, *, lang=None, text=None, chunk_size=None, mode=None)

### Description
Submits a transcript request. If the response contains a jobId, the job is asynchronous and requires polling.

### Parameters
- **url** (str) - Required - The URL to transcribe.
- **lang** (str) - Optional - Language code.
- **text** (bool) - Optional - Whether to return raw text.
- **chunk_size** (int) - Optional - Maps to the API's chunkSize parameter.
- **mode** (str) - Optional - Processing mode: native, auto, or generate.
```

--------------------------------

### client.wait_for_transcript(job, *, interval=2.0, timeout=1200)

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Polls for a transcription job result until completion or timeout.

```APIDOC
## client.wait_for_transcript(job, *, interval=2.0, timeout=1200)

### Description
Waits for a transcription job to complete. Returns content when ready or raises CapslaneError on failure.

### Parameters
- **job** (object) - Required - The job object or ID.
- **interval** (float) - Optional - Polling interval in seconds (default 2.0).
- **timeout** (float) - Optional - Maximum wait time in seconds (default 1200).
```

--------------------------------

### Accepted generation response (HTTP 202)

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

HTTP 202 response for an accepted generation job. jobId, status, and requestId are required; progress is optional. Preserve jobId before waiting so a timeout does not force another submission.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "requestId": "req_example"
}
```

--------------------------------

### Completed job response with content

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Completed job response with stored content. Requires jobId, status, content, lang, availableLangs, source, cached, and requestId. content is always an array of timestamped segments; the endpoint does not return plain text even if text=true was used.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "content": [{ "text": "Synthetic fixture.", "offset": 1000, "duration": 2000, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "generated",
  "cached": true,
  "requestId": "req_example"
}
```

--------------------------------

### client.wait_for_transcript

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

A helper method that polls for a transcript until it is completed, failed, or the timeout is reached.

```APIDOC
## client.wait_for_transcript(job, *, interval=2.0, timeout=1200)

### Description
Polls the job status at the specified interval until completion.

### Parameters
- **job** (str|dict) - Required - The job ID or an accepted-job dictionary.
- **interval** (float) - Optional - Seconds to wait between polls. Defaults to 2.0.
- **timeout** (int) - Optional - Total polling duration in seconds. Defaults to 1200.
```

--------------------------------

### Check an existing job

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Retrieves the status and result of a transcript job using its job_id.

```python
client.transcript_job(job_id: str)
```

--------------------------------

### client.transcript_job(job_id)

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

Checks the status of an existing transcription job.

```APIDOC
## client.transcript_job(job_id)

### Description
Checks the current state of an accepted transcription job once.

### Parameters
- **job_id** (string) - Required - The ID of the job to check.
```

--------------------------------

### Job status response with failed status

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Job status response for a failed job. HTTP 200 does not indicate completion; error is an optional code on a failed job. progress is an optional integer from 0 to 100.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "progress": 50,
  "error": "upstream_unavailable",
  "requestId": "req_example"
}
```

--------------------------------

### client.transcript_job

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Retrieves the status and content of an existing transcription job by its ID.

```APIDOC
## client.transcript_job(job_id: str)

### Description
Performs a GET request to retrieve the status of a specific job.

### Parameters
- **job_id** (str) - Required - The unique identifier of the job.
```

--------------------------------

### Wait for a transcript

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/client.md

Polls for a transcript job until completion or timeout. Accepts a job ID string or a job dictionary.

```python
client.wait_for_transcript(job, *, interval=2.0, timeout=1200)
```

--------------------------------

### Default transcript content structure

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/README.md

The default JSON structure returned by the transcript method, containing segments, language information, and request metadata.

```json
{
  "content": [{ "text": "Example segment.", "offset": 8150, "duration": 1200, "lang": "en" }],
  "lang": "en",
  "availableLangs": ["en"],
  "source": "native",
  "cached": false,
  "requestId": "req_example"
}
```

--------------------------------

### Completed job response without content

Source: https://github.com/webba-creative-technologies/capslane-python/blob/main/docs/http-contract.md

Completed job response without content after stored result expires. This is not a ready transcript; the public endpoint still returns HTTP 200. Bound polling and report missing content to the caller.

```json
{
  "jobId": "job_550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 50,
  "requestId": "req_example"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.