### Install wyrdcraeft using uv

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/installation.rst

Installs the uv tool and then uses it to install the wyrdcraeft package. It's important to ensure that './local/bin' is in your PATH for the executable to be accessible.

```bash
sh -c "$(curl -fsSL https://astral.sh/uv/install)"
uv tool install wyrdcraeft
# Ensure you have ./local/bin in your PATH, since that's where uv puts the
# executable
wyrdcraeft --help
```

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

### Create Wyrdcraeft Configuration File (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/quickstart.rst

This command creates a stub version of the wyrdcraeft configuration file at the appropriate location for your operating system. This file can then be edited to customize wyrdcraeft's behavior.

```bash
wyrdcraeft settings create
```

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

### Install wyrdcraeft from source

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/installation.rst

Clones the wyrdcraeft repository from GitHub, installs the uv tool, and then installs the package from the local source code. This method is suitable for development or using the latest features.

```bash
git clone https://github.com/cmalek/wyrdcraeft.git
sh -c "$(curl -fsSL https://astral.sh/uv/install)"
cd wyrdcraeft
uv tool install .
```

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

### Setup Development Environment with uv

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/runbook/contributing.rst

Installs and configures the 'uv' package manager for setting up the development environment. This involves downloading 'uv', creating a virtual environment, and installing development dependencies.

```shell
$ curl -fsSL https://astral.sh/uv/install | sh
$ uv venv
$ uv sync --dev
```

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

### Development installation of wyrdcraeft

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/installation.rst

Installs the uv tool, clones the wyrdcraeft repository, and then performs a development installation using 'uv sync --dev'. This is intended for users who plan to contribute to the project or need the latest development features.

```bash
sh -c "$(curl -fsSL https://astral.sh/uv/install)"
git clone https://github.com/cmalek/wyrdcraeft.git
cd wyrdcraeft
uv sync --dev
```

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

### Verify wyrdcraeft installation

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/installation.rst

Verifies the installation of the wyrdcraeft package by running its command-line interface (CLI) with the --help flag. This command should work whether the package is installed globally or locally.

```bash
wyrdcraeft --help
```

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

### Install wyrdcraeft from Source

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/faq.rst

Details the steps to install wyrdcraeft directly from its source code repository. This involves cloning the repository and then synchronizing dependencies.

```bash
# Clone the repository and run "uv sync"
# Assuming you have cloned the repository into the current directory
# The specific command to run after cloning would typically be:
uv sync
```

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

### LLM-Assisted Conversion Example (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/command_source_convert.rst

Illustrates how to enable and configure LLM-assisted conversion. This requires API keys to be set in the environment or configuration and allows for more advanced extraction capabilities.

```bash
wyrdcraeft source convert input.txt output.json --use-llm --llm-model gpt-4o
```

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

### Activate virtual environment and verify wyrdcraeft

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/installation.rst

Activates a local virtual environment (assuming it's named '.venv') and then runs the wyrdcraeft CLI with the --help flag to verify the installation within that environment.

```bash
source .venv/bin/activate
wyrdcraeft --help
```

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

### Convert Documents to JSON using LLM with wyrdcraeft

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/faq.rst

Illustrates how to leverage Large Language Models (LLMs) for document conversion to JSON with wyrdcraeft. It includes examples for different LLM providers (OpenAI, Gemini, Ollama) and models, requiring API key setup.

```bash
# Convert a text file to JSON using the gpt-4o model
$ export OPENAI_API_KEY=your-openai-api-key
$ wyrdcraeft source convert --title="My Title" input.txt output.json --use-llm --llm-model="gpt-4o"

# Convert a PDF file to JSON using the gemini-3-flash-preview model
$ export GEMINI_API_KEY=your-gemini-api-key
$ wyrdcraeft source convert --title="My Title" input.pdf output.json --use-llm --llm-model="gemini-3-flash-preview"

# Convert a TEI XML file to JSON using the qwen2.5:14b-instruct model
$ export OLLAMA_API_KEY=your-ollama-api-key
$ wyrdcraeft source convert --title="My Title" input.xml output.json --use-llm --llm-model="qwen2.5:14b-instruct"

# Convert a text file to JSON using the qwen2.5:14b-instruct model
# First run ollama, and pull the model like this:
$ ollama pull qwen2.5:14b-instruct
$ wyrdcraeft source convert --title="My Title" input.txt output.json --use-llm
```

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

### Install wyrdcraeft using pipx

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/faq.rst

Provides the command to install the wyrdcraeft tool using the 'pipx' utility, which installs Python applications in isolated environments. This is a recommended installation method.

```bash
pipx install wyrdcraeft
```

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

### Install wyrdcraeft using uv

Source: https://github.com/cmalek/wyrdcraeft/blob/master/README.md

Installs the wyrdcraeft tool using uv, a fast Python package installer and resolver. It first installs uv itself and then installs wyrdcraeft as a tool, followed by displaying the help command.

```bash
sh -c "$(curl -fsSL https://astral.sh/uv/install)"
uv tool install wyrdcraeft
wyrdcraeft --help
```

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

### TOML Configuration File Example for Wyrdcraeft

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

Example of a TOML configuration file for the wyrdcraeft tool. This file specifies settings for LLM models, API keys, logging, and output formatting. It is loaded with lower priority than environment variables or command-line options.

```toml
[wyrdcraeft]
llm_model_id = "qwen2.5:14b-instruct"
llm_temperature = 0.0
llm_max_tokens = 4096
llm_timeout_s = 120
openai_api_key = "sk-proj-1234567890"
gemini_api_key = "gcp-api-key-1234567890"
log_level = "INFO"
log_file = "/var/log/wyrdcraeft.log"
default_output_format = "json"
enable_colors = true
quiet_mode = false

```

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

### Install wyrdcraeft using uv tool

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/faq.rst

Provides the command to install the wyrdcraeft tool using the 'uv tool' package manager. This is one of the recommended installation methods.

```bash
uv tool install wyrdcraeft
```

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

### Install wyrdcraeft

Source: https://context7.com/cmalek/wyrdcraeft/llms.txt

Installs the wyrdcraeft tool from PyPI, using uv, or from source by cloning the repository.

```bash
# From PyPI
pip install wyrdcraeft

# With uv
uv tool install wyrdcraeft

# From source
git clone https://github.com/cmalek/wyrdcraeft.git
cd wyrdcraeft
uv sync --dev
```

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

### Choose Output Format (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This example shows how to specify the output format for the 'wyrdcraeft settings show' command using the --output flag. Supported formats are 'json' and 'table'.

```bash
wyrdcraeft --output json settings show
```

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

### Specify Base URL and Timeout via Command Line (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This example shows how to use command-line options to specify the base URL and timeout for the directory-api-client. It also demonstrates disabling SSL certificate verification and choosing an output format.

```bash
# Specify base URL
directory-api-client --base-url https://directory.caltech.edu/ buildings list

# Set timeout
directory-api-client --timeout 60 buildings list

# Disable SSL certificate verification
directory-api-client --insecure buildings list

# Choose output format
directory-api-client --output table buildings list
```

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

### Install wyrdcraeft using pip

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/faq.rst

Provides the command to install the wyrdcraeft tool using 'pip', the standard Python package installer. This method installs the package into the current Python environment.

```bash
pip install wyrdcraeft
```

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

### Install wyrdcraeft using pip

Source: https://github.com/cmalek/wyrdcraeft/blob/master/README.md

Installs the wyrdcraeft package from PyPI using pip. This is a standard method for installing Python packages. After installation, it shows how to access the command-line help.

```bash
pip install wyrdcraeft
wyrdcraeft --help
```

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

### Specify Custom Configuration File (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This command-line example illustrates how to specify a custom configuration file for the 'wyrdcraeft settings show' command using the --config-file option.

```bash
wyrdcraeft --config-file /path/to/config.toml settings show
```

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

### Heuristic Conversion Example (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/command_source_convert.rst

Demonstrates a basic heuristic conversion of a plain text file to JSON format without using an LLM. This is the default behavior when no LLM-specific options are provided.

```bash
wyrdcraeft source convert input.txt output.json
```

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

### Enable Verbose Output (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This command-line example shows how to enable verbose output for the 'wyrdcraeft source convert' command. Verbose output can be helpful for debugging.

```bash
wyrdcraeft --verbose source convert /path/to/source.txt /path/to/output.json
```

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

### Basic Wyrdcraeft TOML Configuration Example

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This TOML snippet provides a basic configuration for Wyrdcraeft, including settings for LLM model, temperature, max tokens, timeouts, API keys, log level, log file, default output format, color enablement, and quiet mode.

```toml
# ~/.wyrdcraeft.conf
[wyrdcraeft]
llm_model_id = "qwen2.5:14b-instruct"
llm_temperature = 0.0
llm_max_tokens = 4096
llm_timeout_s = 120
openai_api_key = "sk-proj-1234567890"
gemini_api_key = "gcp-api-key-1234567890"
log_level = "INFO"
log_file = "/var/log/wyrdcraeft.log"
default_output_format = "json"
enable_colors = true
quiet_mode = false
```

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

### Install wyrdcraeft from source

Source: https://github.com/cmalek/wyrdcraeft/blob/master/README.md

Clones the wyrdcraeft repository from GitHub and installs it from source using uv for development. This is typically used for contributing to the project or working with the latest code.

```bash
git clone https://github.com/cmalek/wyrdcraeft.git
cd wyrdcraeft
uv sync --dev
```

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

### Wyrdcraeft Configuration Validation Error Examples (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

Examples of common validation errors encountered during Wyrdcraeft configuration. These errors indicate issues with model IDs, temperature settings, token limits, timeouts, and output formats.

```bash
# Invalid model ID
Error: Invalid model ID: foobar2.5

# Invalid temperature
Error: Temperature must be between 0 and 1

# Invalid max tokens
Error: Max tokens must be greater than 0

# Invalid timeout
Error: Timeout must be greater than 0

# Invalid output format
Error: Invalid output format: foobar
```

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

### Example Changelog Entry in reStructuredText

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/runbook/contributing.rst

An example of how to structure an entry in the changelog file using reStructuredText. It demonstrates the format for version numbers, dates, and categories like Bugfixes, Enhancements, and Documentation.

```rst
.. _changelog__v0.1.0:

0.1.0 (2025-01-01)
------------------

Enhancements
^^^^^^^^^^^^

- Add a new ``my_function2`` function.

Bugfixes
^^^^^^^^

- Fix a bug in the ``my_function`` function.

Documentation
^^^^^^^^^^^^^

- Documented how to use submit a pull request.
```

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

### Configure Wyrdcraeft via Environment Variables (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This example demonstrates how to configure Wyrdcraeft using environment variables in a bash shell. It covers setting the base URL, API timeout, authentication token, and an insecure flag.

```bash
# Set base URL
export DIRECTORY_API_BASE_URL=https://directory.caltech.edu/

# Set timeout
export DIRECTORY_API_TIMEOUT=30.0

# Set authentication token
export DIRECTORY_API_AUTH_TOKEN=2304983209834059430924380593485432987

# Set insecure flag
export DIRECTORY_API_INSECURE=True
```

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

### Setting Log File in TOML

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

Example of specifying a log file path in a TOML configuration file for wyrdcraeft. If not set, logs are directed to the console.

```toml
log_file = "/var/log/wyrdcraeft.log"

```

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

### Install wyrdcraeft using pipx

Source: https://github.com/cmalek/wyrdcraeft/blob/master/README.md

Installs the wyrdcraeft package using pipx, which allows running Python applications in isolated environments. This command installs the package and then demonstrates how to run its help command.

```bash
pipx install wyrdcraeft
wyrdcraeft --help
```

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

### wyrdcraeft CLI Global Options

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/using_cli.rst

Demonstrates common global options available for all wyrdcraeft commands. These include controlling output verbosity, quiet mode, specifying a configuration file, choosing output format, and using environment variables for configuration.

```bash
# Enable verbose output
wyrdcraeft --verbose source convert input.txt output.json

# Enable quiet mode
wyrdcraeft --quiet source convert input.txt output.json

# Use a custom configuration file
wyrdcraeft --config-file /path/to/config.toml source convert input.txt output.json

# Choose output format
wyrdcraeft --output table settings show

# Use environment variables to change configuration
export WYRDCRAEFT_LLM_MODEL_ID="gpt-4o"
$ wyrdcraeft source convert input.txt output.json
```

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

### Create Default Settings File (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/command_settings.rst

Creates a new settings file at the default path with default values. If '--verbose' is set, it also prints a table of the written settings, excluding frozen fields.

```bash
# Create default settings file
wyrdcraeft settings create

# Create with verbose output
wyrdcraeft --verbose settings create
```

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

### Show wyrdcraeft CLI Help

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/using_cli.rst

Displays the main help message for the wyrdcraeft CLI or detailed help for specific command groups and subcommands. This is useful for understanding available commands and their options.

```bash
# Show main help
wyrdcraeft --help

# Show help for specific command groups
wyrdcraeft version --help

# Old English source text commands
wyrdcraeft source convert --help
wyrdcraeft source mark-diacritics --help

# Diacritic index maintenance commands
wyrdcraeft diacritic --help
wyrdcraeft diacritic disambiguate --help
wyrdcraeft diacritic add --help
wyrdcraeft diacritic delete --help

# Settings commands
wyrdcraeft settings --help
wyrdcraeft settings show --help
wyrdcraeft settings create --help

# Old English morphology commands
wyrdcraeft morphology --help
wyrdcraeft morphology generate --help
wyrdcraeft morphology generate-reference-snapshots --help
```

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

### Setting OpenAI API Key in INI

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

Example of setting the OpenAI API key in an INI-like format for wyrdcraeft. This is required when using OpenAI models with the LLMDocumentIngestor.

```ini
openai_api_key = "sk-proj-1234567890"

```

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

### Display Application Settings (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/command_settings.rst

Displays the current application settings. The output format can be controlled using the global '--output' option (json, table, or text).

```bash
# Default: show settings (table format)
wyrdcraeft settings

# Show settings in JSON
wyrdcraeft settings show
wyrdcraeft --output json settings

# Show settings in text format
wyrdcraeft --output text settings show
```

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

### Use Custom Configuration File with wyrdcraeft

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/faq.rst

Demonstrates how to specify a custom configuration file (in TOML format) for wyrdcraeft using the `--config-file` option. This allows for persistent custom settings.

```bash
# Use custom configuration file
wyrdcraeft --config-file /path/to/config.toml source convert --title="My Title" input.txt output.json
```

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

### Enable Quiet Mode (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This command-line example demonstrates how to enable quiet mode for the 'wyrdcraeft' application, suppressing most output. This is useful for scripting or when only specific output is desired.

```bash
wyrdcraeft --quiet source convert /path/to/source.txt /path/to/output.json
```

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

### Setting LLM Timeout in TOML

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

Provides an example of setting the LLM timeout in seconds within a TOML configuration file for wyrdcraeft. This defines the maximum waiting time for an LLM response.

```toml
llm_timeout_s = 60

```

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

### Build and View Sphinx Documentation

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/runbook/contributing.rst

Builds the Sphinx documentation for the project and opens the generated HTML index file. This process ensures documentation is up-to-date and accurate.

```shell
$ cd doc
$ make html
$ open build/html/index.html
```

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

### Python Function with Sphinx Napoleon Docstring

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/runbook/coding_standards.rst

Shows a Python function documented using Sphinx Napoleon format, including sections for Args, Keyword Arguments, Raises, and Returns. It also includes example exception handling.

```python
def my_function(arg1: str, arg2: int, kwarg1: str = "default", kwarg2: int = 10) -> str:
    """
    My function description

    Args:
        arg1: The first argument
        arg2: The second argument

    Keyword Arguments:
        kwarg1: The first keyword argument
        kwarg2: The second keyword argument

    Raises:
        ValueError: If kwarg1 is not 'foo' or 'bar'
        ValueError: If kwarg2 is less than 0

    Returns:
        The result of the function

    """
    if kwarg1 not in ['foo', 'bar']:
        raise ValueError("kwarg1 must be 'foo' or 'bar'")
    if kwarg2 < 0:
        raise ValueError("kwarg2 must be greater than 0")

    return f"{arg1} {arg2}"
```

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

### Secure Configuration File Permissions (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

These bash commands demonstrate how to set appropriate file permissions for Wyrdcraeft configuration files to enhance security. It covers both user-specific and system-wide configurations.

```bash
# Set proper permissions for user-specific config
chmod 600 ~/.wyrdcraeft.conf

# For system-wide configuration
chmod 640 /etc/wyrdcraeft.conf
chown root:root /etc/wyrdcraeft.conf
```

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

### Display Wyrdcraeft Configuration (Bash)

Source: https://github.com/cmalek/wyrdcraeft/blob/master/doc/source/overview/configuration_cli.rst

This command shows how to display the current Wyrdcraeft configuration, which is useful for debugging and verifying that settings are loaded correctly.

```bash
wyrdcraeft settings show
```