Cli

`async_cli_task(file, nodes, update, force, save, context, background, pretty, batch, print_status, progress, model='gpt-3.5-turbo-instruct')` `async`

Executes a task asynchronously.

Parameters:

Name	Type	Description	Default
`file`	`Path`	The file to process.	required
`nodes`	`List`	The nodes to process.	required
`update`	`bool`	Whether to update the task.	required
`force`	`bool`	Whether to force the task.	required
`save`	`bool`	Whether to save the task.	required
`context`	`bool`	Whether to include context.	required
`background`	`bool`	Whether to run the task in the background.	required
`pretty`	`bool`	Whether to format the output.	required
`batch`	`bool`	Whether to run in batch mode.	required
`print_status`	`bool`	Whether to print the status.	required
`progress`	`Progress`	The progress object.	required
`model`	`str`	The model to use for the task. Defaults to "gpt-3.5-turbo-instruct".	`'gpt-3.5-turbo-instruct'`

Returns:

Type	Description
`None`	None

Side Effects

Writes to the file if save is True. Prints the pass/fail status if print_status is True. Pretty prints the result if pretty is True.

Examples:

>>> await async_cli_task(file, nodes, update, force, save, context, background, pretty, batch, print_status, progress)
None

Source code in write_the/cli/tasks.py

async def async_cli_task(
    file: Path,
    nodes: list,
    update: bool,
    force: bool,
    save: bool,
    context: bool,
    background: bool,
    pretty: bool,
    batch: bool,
    print_status: bool,
    progress: Progress,
    model: str = "gpt-3.5-turbo-instruct",
) -> None:
    """
    Executes a task asynchronously.

    Args:
      file (Path): The file to process.
      nodes (List): The nodes to process.
      update (bool): Whether to update the task.
      force (bool): Whether to force the task.
      save (bool): Whether to save the task.
      context (bool): Whether to include context.
      background (bool): Whether to run the task in the background.
      pretty (bool): Whether to format the output.
      batch (bool): Whether to run in batch mode.
      print_status (bool): Whether to print the status.
      progress (Progress): The progress object.
      model (str, optional): The model to use for the task. Defaults to "gpt-3.5-turbo-instruct".

    Returns:
      None

    Side Effects:
      Writes to the file if save is True.
      Prints the pass/fail status if print_status is True.
      Pretty prints the result if pretty is True.

    Examples:
      >>> await async_cli_task(file, nodes, update, force, save, context, background, pretty, batch, print_status, progress)
      None
    """
    task_id = progress.add_task(description=f"{file}", total=None)
    failed = False
    skipped = False
    source_code = load_source_code(file=file)
    if pretty:
        source_code = format_source_code(source_code)
    tree = create_tree(source_code)
    max_batch_size = None
    msg = ""
    if batch:
        max_batch_size = 1
    try:
        result = await write_the_docs(
            tree,
            node_names=nodes,
            update=update,
            force=force,
            save=save,
            context=context,
            background=background,
            pretty=pretty,
            max_batch_size=max_batch_size,
            model=model,
        )
    except ValueError as e:
        msg = f" - {e}"
        failed = True
    except BadRequestError as e:
        msg = f" - {e}"
        failed = True
    except FileSkippedError as e:
        msg = f" - {e}"
        skipped = True

    progress.remove_task(task_id)
    progress.refresh()
    if print_status or save or failed or skipped:
        if skipped:
            icon = "⏭️"
            colour = "yellow"
        elif failed:
            icon = "❌"
            colour = "red" 
        else:
            icon = "✅"
            colour = "green"
        progress.print(
            f"[not underline]{icon} [/not underline][underline]{file}[/underline]{msg}",
            style=f"bold {colour}",
        )
    if failed or skipped:
        return None
    if save:
        with open(file, "w") as f:
            f.writelines(result)
        return None
    if pretty:
        syntax = Syntax(result, "python")
        progress.print(syntax)
    else:
        progress.print(result, highlight=False, markup=False)

`display_models_table(models, default_model, filter_by_company=None, show_free=True)`

Renders the models dictionary into a Rich table.

Source code in write_the/cli/model.py

def display_models_table(models: dict, default_model: str, filter_by_company: Optional[str] = None, show_free: bool = True):
    """Renders the models dictionary into a Rich table."""
    from rich import print
    from rich.table import Table

    table_ = Table()
    table_.add_column("Name", justify="left", style="cyan")
    table_.add_column("Company", justify="left", style="cyan")
    table_.add_column("Context", justify="left", style="magenta")
    table_.add_column("Free", justify="left", style="magenta")
    table_.add_column("Default", justify="left", style="green")

    for name, model in sorted(models.items()):
        # Safeguard against missing context_window key in API response
        context = model.get("context_length", "N/A")
        actual_company = model.get("company", "Unknown")
        is_free = name.split(":")[1] == "free" if ":" in name else False


        if filter_by_company and filter_by_company.lower() != actual_company.lower():
            continue
        if show_free and not is_free:
            continue
        checkmark_default = "✅" if name == default_model else ""
        checkmark_free = "✅" if is_free else ""
        table_.add_row(actual_company, name, str(context), checkmark_free, checkmark_default)

    print(table_)

`fetch_openrouter_models(url='https://openrouter.ai/api/v1/models', api_key=None, timeout=30.0, outfile=None, companies=None)`

Fetch model metadata from OpenRouter and return a dict keyed by model ID.

Source code in write_the/cli/model.py

def fetch_openrouter_models(
        url: str = "https://openrouter.ai/api/v1/models",
        api_key: str | None = None,
        timeout: float = 30.0,
        outfile: Path = None,
        companies: list[str] | None = None,
    ):
    """Fetch model metadata from OpenRouter and return a dict keyed by model ID."""
    headers = {}
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"

    response = requests.get(url, headers=headers, timeout=59)
    response.raise_for_status()

    payload = response.json()
    try:
        data = payload["data"]
    except KeyError as e:
        raise ValueError(f"Unexpected API response: missing 'data' key. Keys: {list(payload.keys())}") from e

    # ormodels = {m["id"]: m for m in data if "id" in m}
    ormodels = {
        m["id"]: m | {"company": m["id"].split('/')[0]}
        for m in data
        if "id" in m and (companies is None or m["id"].split('/')[0] in companies)
    }

    if outfile:
        with open(outfile, 'w', encoding='utf-8') as f:
            json.dump(ormodels, f, indent=4)

    return ormodels