# KnowledgeBase

Share immutable knowledge across parsers, transform engines, and documents.

https://texform.dev/api/python/knowledge-base

## `KnowledgeBase`

Kind: class

```python
KnowledgeBase(packages: list[str] | None = None, items: list[ContextItem] | None = None, remove_commands: list[str] | None = None, remove_environments: list[str] | None = None, remove_delimiter_controls: list[str] | None = None) -> None
```

Immutable knowledge shared by parsers, engines, and documents.

A knowledge base defines the known commands, environments, characters, and delimiters that parsing, transforms, and ``Document`` construction and edits check against. Share one instance across a ``Parser``, ``TransformEngine``, and their documents.

Equality and hashing use instance identity: separately constructed knowledge bases are distinct even with identical recipes. Query results are copies. ``packages=None`` loads the default runtime packages; ``[]`` loads none.

```python
kb = texform.KnowledgeBase(["ams"])
doc = texform.Parser(kb).parse(r"\frac{a}{b}")["document"]
```

#### `KnowledgeBase`

```python
KnowledgeBase(packages: list[str] | None = None, items: list[ContextItem] | None = None, remove_commands: list[str] | None = None, remove_environments: list[str] | None = None, remove_delimiter_controls: list[str] | None = None) -> None
```

Build the knowledge base once.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `packages` | list[str] | None | None | Package names to load, or ``None`` for the defaults. |
| `items` | list[ContextItem] | None | None | Extra command, environment, or delimiter items to add. |
| `remove_commands` | list[str] | None | None | Command names to remove after loading. |
| `remove_environments` | list[str] | None | None | Environment names to remove after loading. |
| `remove_delimiter_controls` | list[str] | None | None | Delimiter control names to remove after loading. |

- `ConfigError`: If a package name or an item is invalid.

#### `__eq__`

```python
__eq__(other: object) -> bool
```

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `other` | object | — |  |

**Returns** `bool`

#### `__hash__`

```python
__hash__() -> int
```

**Returns** `int`

#### `packages`

```python
packages() -> list[str]
```

Return the loaded package names in canonical order.

**Returns** `list[str]`

#### `commands`

```python
commands(mode: Literal['math', 'text']) -> list[dict[str, Any]]
```

Return the command records for ``mode``, sorted by name.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Literal['math', 'text'] | — |  |

**Returns** `list[dict[str, Any]]`

#### `environments`

```python
environments(mode: Literal['math', 'text']) -> list[dict[str, Any]]
```

Return the environment records for ``mode``, sorted by name.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Literal['math', 'text'] | — |  |

**Returns** `list[dict[str, Any]]`

#### `characters`

```python
characters(mode: Literal['math', 'text']) -> list[dict[str, Any]]
```

Return the character records for ``mode``, sorted by name.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Literal['math', 'text'] | — |  |

**Returns** `list[dict[str, Any]]`

#### `delimiters`

```python
delimiters() -> list[dict[str, Any]]
```

Return delimiter records sorted by name.

**Returns** `list[dict[str, Any]]`

#### `lookup_command`

```python
lookup_command(name: str, mode: Literal['math', 'text']) -> dict[str, Any] | None
```

Look up the full knowledge entry for a command in a given mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The command name without the leading backslash. |
| `mode` | Literal['math', 'text'] | — | ``"math"`` or ``"text"``. |

**Returns** `dict[str, Any] | None` A dict describing the command, including its parsed ``args`` slots, or ``None`` if the command is unknown in that mode.

#### `lookup_explicit_command`

```python
lookup_explicit_command(name: str, mode: Literal['math', 'text']) -> dict[str, Any] | None
```

Look up the knowledge entry for an explicit command in a given mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The command name without the leading backslash. |
| `mode` | Literal['math', 'text'] | — | ``"math"`` or ``"text"``. |

**Returns** `dict[str, Any] | None` A knowledge-entry dict, or ``None`` if unknown in that mode.

#### `lookup_character`

```python
lookup_character(name: str, mode: Literal['math', 'text']) -> dict[str, Any] | None
```

Look up the knowledge entry for a character in a given mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The character name without the leading backslash. |
| `mode` | Literal['math', 'text'] | — | ``"math"`` or ``"text"``. |

**Returns** `dict[str, Any] | None` A knowledge-entry dict, or ``None`` if unknown in that mode.

#### `lookup_env`

```python
lookup_env(name: str, mode: Literal['math', 'text']) -> dict[str, Any] | None
```

Look up the knowledge entry for an environment in a given mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The environment name. |
| `mode` | Literal['math', 'text'] | — | ``"math"`` or ``"text"``. |

**Returns** `dict[str, Any] | None` A knowledge-entry dict, or ``None`` if unknown in that mode.

#### `is_delimiter_control`

```python
is_delimiter_control(name: str) -> bool
```

Report whether a name is a delimiter control such as ``langle``.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The control name without the leading backslash. |

**Returns** `bool` ``True`` if the name is a known delimiter control.

```python
texform.KnowledgeBase().is_delimiter_control("langle")  # True
```

#### `knows_command_name`

```python
knows_command_name(name: str) -> bool
```

Report whether a command name is known, ignoring mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The command name without the leading backslash. |

**Returns** `bool` ``True`` if the command is known in any mode.

#### `knows_env_name`

```python
knows_env_name(name: str) -> bool
```

Report whether an environment name is known, ignoring mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The environment name. |

**Returns** `bool` ``True`` if the environment is known in any mode.

#### `knows_character_name`

```python
knows_character_name(name: str) -> bool
```

Report whether a character name is known, ignoring mode.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | str | — | The character name without the leading backslash. |

**Returns** `bool` ``True`` if the character is known in any mode.

## `CommandItem`

Kind: typedDict

A custom command injected into parser knowledge.

| Name | Type | Description |
| --- | --- | --- |
| `target` | Literal['command'] | Discriminator; always ``"command"``. |
| `name` | str | Command name without the leading backslash. |
| `kind` | Literal['prefix', 'infix', 'declarative'] | Syntactic role: ``"prefix"``, ``"infix"``, or ``"declarative"``. |
| `allowed_mode` | Literal['math', 'text', 'both'] | Modes in which the command is valid: ``"math"``, ``"text"``, or ``"both"``. |
| `argspec` | str | xparse-style argument specification, such as ``"m m"`` or ``"o m"``. |
| `tags` | NotRequired[list[str]] | Optional free-form classification tags carried into the knowledge entry. |

## `EnvironmentItem`

Kind: typedDict

A custom environment injected into parser knowledge.

| Name | Type | Description |
| --- | --- | --- |
| `target` | Literal['environment'] | Discriminator; always ``"environment"``. |
| `name` | str | Environment name as written in ``\begin{...}``. |
| `allowed_mode` | Literal['math', 'text', 'both'] | Modes in which the environment may appear. |
| `body_mode` | Literal['math', 'text'] | Content mode of the environment body (``"math"`` or ``"text"``). |
| `argspec` | str | xparse-style argument specification for the environment header. |
| `tags` | NotRequired[list[str]] | Optional free-form classification tags. |

## `DelimiterItem`

Kind: typedDict

A custom delimiter control injected into parser knowledge.

| Name | Type | Description |
| --- | --- | --- |
| `target` | Literal['delimiter'] | Discriminator; always ``"delimiter"``. |
| `name` | str | Delimiter-control name without the leading backslash (for example ``"langle"``). |