# Glossary

## Overview

Glossary prompts define domain-specific terms, descriptions, and synonyms that agents use to understand specialized vocabulary. Each entry contains a term name, description, and list of synonyms.

Glossary prompts are stored as text prompts on the platform. The SDK parses the YAML or JSON content into typed Python objects.

***

## Convenience methods

These methods automatically apply the folder prefix and `type="glossary"`, so you don't have to.

## `get_glossary` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3772)

Get a glossary prompt by name.

Automatically prefixes the name with `glossaries/` and sets `type="glossary"`.

```python
get_glossary(
    name: str,
    *,
    version: int | None = None,
    label: str | None = None,
    cache_ttl_seconds: int | None = None,
    fallback: str | None = None,
    max_retries: int | None = None,
    fetch_timeout_seconds: int | None = None,
) -> GlossaryPromptClient
```

**Parameters**

* `name` — Glossary name (without the `glossaries/` prefix).
* `version` — Optional version number.
* `label` — Optional label filter.
* `cache_ttl_seconds` — Cache TTL override.
* `fallback` — Fallback YAML/JSON content string.
* `max_retries` — Maximum number of retries.
* `fetch_timeout_seconds` — Fetch timeout override.

**Returns**

GlossaryPromptClient

***

## `create_glossary` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3810)

Create a glossary prompt.

Automatically prefixes the name with `glossaries/` and sets `type="glossary"`.

```python
create_glossary(
    *,
    name: str,
    prompt: str,
    labels: List[str] | None = None,
    tags: List[str] | None = None,
    config: Any | None = None,
    commit_message: str | None = None,
) -> GlossaryPromptClient
```

**Parameters**

* `name` — Glossary name (without the `glossaries/` prefix).
* `prompt` — JSON content string.
* `labels` — Labels to assign.
* `tags` — Tags to assign.
* `config` — Additional config dict.
* `commit_message` — Optional commit message.

**Returns**

GlossaryPromptClient

***

## `update_glossary` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3845)

Update a glossary prompt version.

Automatically sets `type="glossary"` and routes through the type-specific endpoint.

```python
update_glossary(
    *,
    name: str,
    version: int,
    new_labels: List[str] | None = None,
) -> Any
```

**Parameters**

* `name` — Glossary name (without the `glossaries/` prefix).
* `version` — The version number of the prompt to update.
* `new_labels` — New labels to assign to the prompt version.

**Returns**

The updated prompt from the InteractiveAI API.

***

## `list_glossaries` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3869)

List glossary prompts.

```python
list_glossaries(
    *,
    label: str | None = None,
    tag: str | None = None,
    page: int | None = None,
    limit: int | None = None,
) -> PromptMetaListResponse
```

**Parameters**

* `label` — Optional label filter.
* `tag` — Optional tag filter.
* `page` — Page number.
* `limit` — Items per page.

**Returns**

PromptMetaListResponse

***

## `delete_glossary` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3892)

Delete a glossary prompt.

Automatically prefixes the name with `glossaries/`.

```python
delete_glossary(
    name: str,
    *,
    label: str | None = None,
    version: int | None = None,
) -> None
```

**Parameters**

* `name` — Glossary name (without the `glossaries/` prefix).
* `label` — If set, deletes versions carrying this label.
* `version` — If set, deletes only this specific version.

***

## Fetching glossary

```python
glossary = client.get_glossary("finance-terms")

for term in glossary.entries:
    print(term.name, term.description, term.synonyms)
```

***

## Creating glossary

```python
content = """
{
  "terms": [
    {
      "name": "RIB",
      "description": "Official document required to validate a bank account for withdrawals.",
      "synonyms": ["bank details"]
    },
    {
      "name": "BALANCE_REAL",
      "description": "Amount of real money (cash) in the account.",
      "synonyms": ["real balance", "cash balance"]
    }
  ]
}
"""

glossary = client.create_glossary(
    name="finance-terms",
    prompt=content,
    labels=["production"],
)
```

The SDK validates the YAML structure on create and raises `ValueError` if the content is malformed.

***

## `GlossaryPromptClient`

Returned by `get_glossary()` and `create_glossary()`.

**Attributes**

* `name` — Prompt name.
* `version` — Prompt version number.
* `labels` — List of labels (e.g. `["production"]`).
* `tags` — List of tags.
* `config` — Arbitrary config dict stored with the prompt.
* `is_fallback` — `True` if this was returned from a fallback value.
* `raw_content` — The original unparsed text content.
* `entries` — `List[GlossaryEntry]` (property).

**Methods**

* `compile()` — Returns the parsed `GlossaryContent` dataclass. Template variable substitution does not apply to structured prompts.
* `variables` — Always returns an empty list.

***

## `GlossaryEntry`

Dataclass representing a single glossary term.

| Field         | Type        | Description                                     |
| ------------- | ----------- | ----------------------------------------------- |
| `name`        | `str`       | Term name (e.g. `"RIB"`).                       |
| `description` | `str`       | Human-readable description of the term.         |
| `synonyms`    | `List[str]` | Alternative names or translations for the term. |

***

## Content format

Glossary can be authored in YAML or JSON. JSON is recommended for readability.

```json
{
  "terms": [
    {
      "name": "WITHDRAWABLE_BALANCE",
      "description": "Total amount the player can withdraw right now.",
      "synonyms": ["withdrawable balance", "available for withdrawal"]
    },
    {
      "name": "KYC_STATUS",
      "description": "Know Your Customer verification status.",
      "synonyms": ["KYC", "identity verification"]
    }
  ]
}
```