### Installation

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

Instructions for installing the ModelForge library, including recommended virtual environment setup and a quick system-wide installation option.

```bash
# Create and activate virtual environment
python -m venv model-forge-env
source model-forge-env/bin/activate  # On Windows: model-forge-env\Scripts\activate

# Install package
pip install model-forge-llm

# Verify installation
modelforge --help
```

```bash
pip install model-forge-llm
```

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

### Main Project Documentation

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/README.md

Points to the main README.md file in the project root for general usage, installation instructions, and quick start guides.

```markdown
[README.md](../README.md)
```

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

### README.md Installation and Development Setup

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/design.md

Markdown snippets for updating a README file, showing recommended installation methods using UV and pip, and detailing the steps for setting up a development environment with UV, including cloning the repository, installing UV, creating a virtual environment, and running tests.

```markdown
## Installation

### Using UV (Recommended)
```bash
pip install uv
uv pip install modelforge
```

### Using pip
```bash
pip install modelforge
```
```

```markdown
### Development Setup

```bash
# Clone repository
git clone https://github.com/smiao-icims/model-forge.git
cd model-forge

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup development environment
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
uv run pytest
```
```

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

### Updated setup.sh for UV Migration

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/design.md

A bash script to automate the setup process for UV, including checking for UV installation, creating a virtual environment, installing dependencies, and running tests.

```bash
#!/bin/bash
# Updated setup.sh for UV

# Check for UV installation
if ! command -v uv &> /dev/null;
then
    echo "Installing UV..."
    curl -LsSf https://astral.sh/uv/install.sh | sh
fi

# Create virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

```

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

### Model Forge Development Setup

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

Outlines the steps for setting up the Model Forge development environment. Includes cloning the repository, installing dependencies using uv, and running tests. Mentions Python 3.11+ and uv as requirements.

```bash
git clone https://github.com/smiao-icims/model-forge.git
cd model-forge

# Quick setup with uv (recommended)
./setup.sh

# Or manual setup
uv sync --extra dev
uv run pytest
```

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

### Browser Pilot Integration Guide

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/README.md

Provides a complete guide for integrating Browser Pilot with ModelForge version 2.2 and later. Includes API examples and solutions for compatibility issues.

```markdown
[BROWSER_PILOT_INTEGRATION.md](BROWSER_PILOT_INTEGRATION.md)
```

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

### Run Interactive Configuration Wizard

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/RELEASE_NOTES_v2.3.0.md

This command initiates the interactive configuration wizard for ModelForge, guiding users through the setup process.

```bash
modelforge config
```

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

### Documentation Structure

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/nodejs-port/tasks.md

Outlines the comprehensive documentation plan, including a detailed README with examples, API documentation, a migration guide from Python, example scripts, configuration format documentation, a troubleshooting guide, and a comparison table with the Python version.

```markdown
# ModelForge Node.js

## Table of Contents

1.  [Introduction](#introduction)
2.  [Getting Started](#getting-started)
3.  [Core Concepts](#core-concepts)
    *   [Providers](#providers)
    *   [Configuration](#configuration)
    *   [Authentication](#authentication)
4.  [Usage](#usage)
    *   [Basic Example](#basic-example)
    *   [CLI Commands](#cli-commands)
5.  [API Reference](#api-reference)
6.  [Migration Guide (Python to Node.js)](#migration-guide)
7.  [Troubleshooting](#troubleshooting)
8.  [Comparison with Python Version](#comparison)

## Introduction

ModelForge provides a unified interface for interacting with various Large Language Models (LLMs), abstracting away the complexities of different provider APIs. This Node.js implementation aims to offer similar functionality and ease of use as the Python version.

## Getting Started

```bash
npm install model-forge-node
```

## Core Concepts

### Providers

ModelForge supports multiple LLM providers including:

*   OpenAI
*   Google Generative AI
*   Anthropic
*   Ollama (Experimental)

### Configuration

Configuration can be managed via a JSON file or programmatically. See [Configuration Management](#configuration-management) for details.

### Authentication

API keys and other credentials can be managed securely. See [Authentication Management](#authentication-management) for details.

## Usage

### Basic Example

```javascript
const { ModelForge } = require('model-forge-node');

async function main() {
  const config = {
    provider: 'openai',
    apiKey: 'YOUR_OPENAI_API_KEY'
  };
  const modelForge = new ModelForge(config);
  const llm = await modelForge.getLLM();
  
  const response = await llm.chat.completions.create({
    messages: [{ role: 'user', content: 'Hello!' }],
    model: 'gpt-3.5-turbo',
  });
  console.log(response.choices[0].message.content);
}

main();
```

### CLI Commands

```bash
# Show current configuration
model-forge config show

# Add a new model configuration
# model-forge config add <name> <config_json>

# Set the current model
# model-forge config use <name>
```

## API Reference

Refer to the generated [API Documentation](link-to-api-docs) for detailed information on classes, methods, and parameters.

## Migration Guide (Python to Node.js)

This guide outlines the key differences and steps required to migrate from the Python ModelForge implementation to this Node.js version.

## Troubleshooting

Common issues and their solutions.

## Comparison with Python Version

| Feature             | Python Version | Node.js Version | Notes                                  |
|---------------------|----------------|-----------------|----------------------------------------|
| OpenAI Support      | ✅             | ✅              |                                        |
| Google GenAI Support| ✅             | ✅              |                                        |
| Anthropic Support   | ✅             | ✅              |                                        |
| Ollama Support      | ✅             | Experimental    |                                        |
| Configuration Mgmt  | ✅             | ✅              | JSON-based, scope handling             |
| Authentication      | ✅             | ✅              | API Keys, Device Flow (GitHub)         |
| CLI                 | ✅             | ✅              | Commander.js based                     |
| Telemetry           | ✅             | ✅              | LangChain.js, OpenTelemetry compatible |
| Build               | N/A            | ESM/CJS         | Dual module support                    |

```

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

### Setup Development Environment with uv

Source: https://github.com/smiao-icims/model-forge/blob/main/CONTRIBUTING.md

Installs uv (a modern Python package manager) and sets up the development environment by installing dependencies and pre-commit hooks.

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and setup pre-commit
uv sync --extra dev
uv run pre-commit install
```

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

### Discover Available Models

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/BROWSER_PILOT_INTEGRATION.md

Fetches all available LLM models, optionally filtered by a specific provider. The example shows how to get all models and then how to retrieve models specifically for the 'openai' provider, printing their display names and context lengths, along with pricing information if available.

```python
# Get all available models
all_models = registry.get_available_models()

# Get models for specific provider
openai_models = registry.get_available_models(provider="openai")
for model in openai_models:
    print(f"{model['display_name']}: {model['context_length']:,} tokens")
    if model.get('pricing'):
        price = model['pricing'].get('input_per_1m_tokens', 0)
        print(f"  Cost: ${price}/1M tokens")
```

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

### Verify Development Setup

Source: https://github.com/smiao-icims/model-forge/blob/main/CONTRIBUTING.md

Verifies the development setup by checking the modelforge CLI help and running tests.

```bash
uv run modelforge --help
uv run pytest tests/ -v
```

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

### Local Ollama Setup and Usage

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

Guides users on how to configure and use local Ollama models with ModelForge, requiring Ollama to be running locally.

```bash
# Make sure Ollama is running locally
# Then add a local model
modelforge config add --provider ollama --model qwen3:1.7b

# Select the local model
modelforge config use --provider ollama --model qwen3:1.7b

# Test your setup
modelforge test --prompt "What is machine learning?"
```

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

### Browser Pilot LLM Integration Example

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/BROWSER_PILOT_INTEGRATION.md

Demonstrates how to automatically select and configure an LLM for use in Browser Pilot. The `setup_browser_pilot_llm` function iterates through preferred providers, checks for configuration, and retrieves an enhanced LLM instance. It prints details like context length and vision support, returning the selected LLM or raising an exception if none is found.

```python
from modelforge.registry import ModelForgeRegistry

def setup_browser_pilot_llm():
    """Smart LLM selection for Browser Pilot."""
    registry = ModelForgeRegistry()

    # Find best configured provider for Browser Pilot
    for provider in ["openai", "anthropic", "github_copilot"]:
        if registry.is_provider_configured(provider):
            models = registry.get_configured_models(provider)
            if models:
                # Use first available model
                model_alias = list(models.keys())[0]

                # Get enhanced LLM with metadata
                llm = registry.get_llm(
                    provider_name=provider,
                    model_alias=model_alias,
                    enhanced=True  # Required for model_info property
                )

                print(f"Using {provider}/{model_alias}")
                print(f"Context: {llm.context_length:,} tokens")
                print(f"Vision: {llm.supports_vision}")

                return llm

    raise Exception("No suitable LLM provider configured")

# Usage in Browser Pilot
llm = setup_browser_pilot_llm()
```

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

### GitHub Actions Release Workflow Example

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/tasks.md

Illustrative configuration for a GitHub Actions workflow to automate releases, including build, test, and PyPI publishing steps. This snippet is based on the described CI/CD setup for ModelForge.

```yaml
name: Release


on:
  push:
    tags:
      - 'v*'


jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build wheel twine
          pip install -r requirements.txt # Assuming a requirements.txt for build/test
      - name: Build package
        run: python -m build
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@27b3170224f3a490697a73727175323477b07808
        with:
          repository-url: https://upload.pypi.org/legacy/
          api-token: ${{ secrets.PYPI_API_TOKEN }}
          packages-dir: ./dist/
```

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

### Installation from PyPI

Source: https://github.com/smiao-icims/model-forge/blob/main/PUBLISHING.md

Installs the `model-forge-llm` package from the production PyPI repository using pip.

```bash
pip install model-forge-llm
```

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

### Installation from TestPyPI

Source: https://github.com/smiao-icims/model-forge/blob/main/PUBLISHING.md

Installs the `model-forge-llm` package from the TestPyPI repository, specifying the `--index-url` to point to the test repository.

```bash
pip install --index-url https://test.pypi.org/simple/ model-forge-llm
```

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

### Python Package Build Configuration (pyproject.toml)

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/tasks.md

Example snippet of a pyproject.toml file configuring the build system for setuptools, including project metadata and package discovery for a src layout. This reflects the setup for ModelForge.

```toml
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "model-forge-llm"
version = "1.0.0"
description = "A library for model orchestration."
readme = "README.md"
requires-python = ">=3.8"
license = {
    "file" = "LICENSE"
}
keywords = ["llm", "model", "forge", "orchestration"]
authors = [
    { name="Your Name", email="your.email@example.com" },
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/yourusername/model-forge"

```

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

### Local Development Workflow with UV

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/design.md

Demonstrates the steps for setting up and running a project locally using UV, including installation, environment creation, dependency installation, and running commands.

```bash
# Install UV
pip install uv

# Create virtual environment
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run CLI
uv run modelforge config show

```

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

### Testing CLI Functionality

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/tasks.md

Example of how to test the CLI commands after installing the package in a clean environment. This ensures the entry points are correctly configured and functional.

```bash
modelforge --help
modelforge --version
# Add other CLI command tests here

```

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

### UV Project Initialization and Dependency Installation

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/design.md

Steps to initialize a UV virtual environment and install project dependencies, including development dependencies.

```bash
# Create UV environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"

```

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

### CLI Streaming Examples (Bash)

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/v2.1-release-notes.md

Illustrates using the `--stream` flag in the ModelForge CLI for real-time output. Includes examples for streaming to the console, to a file, and with different provider configurations.

```bash
modelforge test --prompt "Write a detailed story" --stream

modelforge test --prompt "Explain quantum computing" --stream --output-file explanation.txt

modelforge config use --provider ollama --model qwen3:1.7b
modelforge test --prompt "What is machine learning?" --stream

modelforge config use --provider github_copilot --model claude-3.7-sonnet
modelforge test --prompt "Explain AI" --stream
```

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

### Example Usage Scripts

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/requirements.md

Example scripts will be provided to demonstrate how to use the ModelForge library for common tasks, aiding user adoption and understanding.

```python
# Example usage script (conceptual)
# from modelforge.models import Model
# from modelforge.config import load_config
#
# # Load configuration
# config = load_config('path/to/config.yaml')
#
# # Create a model
# my_model = Model.create(name='my_first_model', config=config['model_settings'])
#
# # Train the model (example)
# # my_model.train(data='path/to/data.csv')
#
# print(f"Model '{my_model.name}' created successfully.")
```

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

### Manual Release: Install Build Tools

Source: https://github.com/smiao-icims/model-forge/blob/main/PUBLISHING.md

Installs the necessary build tools, `build` and `twine`, using `uv` for dependency management. These tools are required for building and uploading Python packages.

```bash
uv add --dev build twine
```

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

### PyPI Installation Verification

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/tasks.md

Verifies that the 'model-forge-llm' package can be successfully installed using pip.

```bash
pip install model-forge-llm
```

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

### Installation Verification

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/design.md

Provides commands to verify the installation and basic functionality of the ModelForge package in a clean environment using Docker.

```bash
# Test installation in clean environment
docker run --rm python:3.11 pip install modelforge
modelforge --help

# Verify CLI functionality
modelforge config show
```

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

### Manual Release: Validate Package

Source: https://github.com/smiao-icims/model-forge/blob/main/PUBLISHING.md

Validates the built package using `twine check` to ensure integrity and then tests the installation locally by installing the wheel file and running the CLI command.

```bash
# Check package integrity
uv run twine check dist/*

# Test installation locally
pip install dist/*.whl
modelforge --help
```

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

### Node.js Project Setup with TypeScript

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/nodejs-port/tasks.md

Initializes a Node.js project with TypeScript configuration, ESM module structure, Vitest for testing, and CI/CD setup. Includes configuring linting (ESLint) and formatting (Prettier).

```bash
npm init -y
npx tsc --init --module esnext --target es2020 --outDir dist --rootDir src --strict --esModuleInterop --skipLibCheck
```

```json
{
  "name": "model-forge-node",
  "version": "1.0.0",
  "description": "",
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts",
  "scripts": {
    "test": "vitest",
    "build": "tsc",
    "lint": "eslint . --ext .ts",
    "format": "prettier --write ."
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/node": "^20.0.0",
    "eslint": "^8.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0"
  }
}
```

```javascript
// .eslintrc.js
module.exports = {
  root: true,
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    // Add custom rules here
  }
};
```

```javascript
// .prettierrc.js
module.exports = {
  semi: true,
  trailingComma: 'all',
  singleQuote: true,
  printWidth: 100,
  tabWidth: 2
};
```

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

### OpenTelemetry Integration Guide

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/v2.1/opentelemetry-integration/tasks.md

Provides guidance on integrating OpenTelemetry with Model Forge, covering installation, basic configuration, and examples for common frameworks like FastAPI and Celery.

```APIDOC
OpenTelemetry Integration Guide:

1. Installation:
   Install with optional dependencies:
   ```bash
   pip install "model-forge[otel]"
   ```

2. Configuration:
   Enable OpenTelemetry in your settings:
   ```yaml
   opentelemetry:
     enabled: true
     service_name: "my-llm-service"
     attributes:
       environment: "staging"
   ```

3. Usage Examples:

   a. FastAPI Integration:
      ```python
      from fastapi import FastAPI
      from model_forge import ModelForgeRegistry
      from model_forge.callbacks.telemetry import TelemetryCallback
      from model_forge.utils.otel import is_otel_available, get_tracer
      import os

      app = FastAPI()

      # Configure OpenTelemetry (e.g., using environment variables or a config file)
      # For demonstration, assuming config is loaded elsewhere
      config = {
          "opentelemetry": {
              "enabled": True,
              "service_name": "fastapi-model-forge"
          }
      }

      registry = ModelForgeRegistry(config)
      otel_enabled = registry.otel_enabled
      tracer = registry.tracer

      # Initialize callback with OTel support
      callback = TelemetryCallback(otel_enabled=otel_enabled, tracer=tracer)

      @app.get("/invoke_llm")
      async def invoke_llm_endpoint():
          llm = registry.get_llm("openai", "gpt-3.5-turbo", "chat")
          # Simulate LLM call with callback
          llm.invoke("Hello", callbacks=[callback])
          return {"message": "LLM invoked"}
      ```

   b. Celery Integration:
      Celery tasks can also be instrumented. Ensure the OpenTelemetry SDK is initialized in the Celery worker.
      ```python
      from celery import Celery
      from model_forge import ModelForgeRegistry
      from model_forge.callbacks.telemetry import TelemetryCallback
      from model_forge.utils.otel import is_otel_available, get_tracer

      app = Celery('tasks', broker='redis://localhost:6379/0')

      # Assume config is loaded and registry/callback are initialized
      config = {
          "opentelemetry": {
              "enabled": True,
              "service_name": "celery-model-forge"
          }
      }
      registry = ModelForgeRegistry(config)
      callback = TelemetryCallback(otel_enabled=registry.otel_enabled, tracer=registry.tracer)

      @app.task
      def process_llm_request(prompt: str):
          llm = registry.get_llm("anthropic", "claude-3-opus", "chat")
          llm.invoke(prompt, callbacks=[callback])
          return "Processed"
      ```

4. Backend Setup:
   Configure your tracing backend (e.g., Jaeger, Zipkin, Datadog) to receive spans.
   Ensure the OpenTelemetry SDK is configured to export traces to your chosen backend.

```

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

### OpenAI Setup and Usage

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

Provides instructions for setting up and using OpenAI models, including API key authentication and model selection.

```bash
# Add OpenAI with your API key
modelforge auth login --provider openai --api-key YOUR_API_KEY

# Select GPT-4o-mini
modelforge config use --provider openai --model gpt-4o-mini

# Test your setup
modelforge test --prompt "Hello, world!"
```

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

### GitHub Copilot Setup and Usage

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

Demonstrates how to discover, authenticate, configure, and test with GitHub Copilot models using the ModelForge CLI.

```bash
# Discover GitHub Copilot models
modelforge models list --provider github_copilot

# Set up GitHub Copilot with device authentication
modelforge auth login --provider github_copilot

# Select Claude 3.7 Sonnet via GitHub Copilot
modelforge config use --provider github_copilot --model claude-3.7-sonnet

# Test your setup
modelforge test --prompt "Write a Python function to reverse a string"
```

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

### Interactive Configuration Wizard

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

Launches an interactive wizard to guide users through setting up LLM providers, authentication, and model selection.

```bash
# Launch the interactive wizard
modelforge config

# The wizard will guide you through:
# 1. Choosing a provider (with recommendations)
# 2. Setting up authentication
# 3. Selecting a model
# 4. Testing your configuration
```

```bash
# Alternative wizard launch
modelforge config --wizard
```

```bash
# Debug mode with logs
modelforge config --wizard --verbose
```

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

### ModelForge Upgrade and Verification

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/BROWSER_PILOT_INTEGRATION.md

Instructions for upgrading ModelForge and verifying the Browser Pilot integration by running a test command.

```bash
# Install/upgrade ModelForge
pip install --upgrade model-forge-llm>=2.2.1

# Run Browser Pilot with enhanced mode
uv run browser-pilot examples/test.md --provider github_copilot --model gpt-4o --verbose
```

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

### Documentation: Type Usage Examples

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/type-safety-refactor/tasks.md

Outlines the necessary updates to project documentation to include examples demonstrating the usage of type hints and type-safe patterns. This includes updating the README, creating a contributor guide, and enhancing API and development documentation.

```APIDOC
README.md:
  - Add a section 'Getting Started with Type Safety'.
  - Include a simple Python snippet showing how to instantiate and use a typed configuration object:
    ```python
    from model_forge.types import ModelForgeConfig

    config = ModelForgeConfig(model_name='gpt-4', api_key='sk-...', max_tokens=1000)
    print(f"Using model: {config['model_name']}")
    ```

Contributor Guide:
  - Detail the project's commitment to type safety.
  - Explain how to add new types using `TypedDict`.
  - Provide guidelines for writing type-hinted functions and classes.
  - Describe the role of Mypy and how to run it locally.

API Documentation:
  - Ensure all function and method signatures include type hints.
  - Document the expected types for all parameters and return values.
  - Example:
    ```python
    class Registry:
        def register_model(self, config: ModelForgeConfig) -> None:
            """Registers a model configuration.

            Args:
                config: A ModelForgeConfig object containing model details.
            
            Returns:
                None
            
            Raises:
                ConfigError: If the provided config is invalid.
            """
            # ... implementation ...
    ```

Development Docs:
  - Include a dedicated section on 'Type Checking with Mypy'.
  - Explain the Mypy configuration (`mypy.ini`) and strict mode.
  - Provide commands to run Mypy checks locally.
  - Document the process of adding type annotations to existing code.

```

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

### Profile Initialization Command

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/v2.1/config-improvements/tasks.md

Details for the 'profile init' command, which guides users through an interactive setup process, allowing template selection and customization.

```APIDOC
profile init
  - Guides user through initial project setup.
  - Prompts for profile selection (e.g., from templates).
  - Allows customization of selected profile parameters.
  - Creates the initial configuration file with the chosen profile.
```

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

### Get Enhanced LLM Instance

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/BROWSER_PILOT_INTEGRATION.md

Demonstrates how to retrieve an enhanced LLM instance from the ModelForge registry, which includes additional metadata and features.

```python
from modelforge.registry import ModelForgeRegistry
from modelforge.enhanced_llm import EnhancedLLM

registry = ModelForgeRegistry()

# Get enhanced LLM
llm = registry.get_llm(enhanced=True)

# Type check for safety
if isinstance(llm, EnhancedLLM):
    print(f"Model: {llm.model_info['name']}")
    print(f"Context: {llm.context_length:,} tokens")
    print(f"Vision: {llm.supports_vision}")

    # Estimate cost for 1000 input + 500 output tokens
    cost = llm.estimate_cost(1000, 500)
    print(f"Estimated cost: ${cost:.6f}")
```

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

### Manual Release: Test on TestPyPI

Source: https://github.com/smiao-icims/model-forge/blob/main/PUBLISHING.md

Uploads the package to TestPyPI for testing and then demonstrates how to install it from TestPyPI to verify the publishing process before deploying to the production PyPI.

```bash
# Upload to TestPyPI first
uv run twine upload --repository testpypi dist/*

# Test installation from TestPyPI
pip install --index-url https://test.pypi.org/simple/ model-forge-llm
```

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

### CI/CD GitHub Actions Workflow with UV

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/design.md

An example GitHub Actions workflow that utilizes UV for setting up Python, installing dependencies, and running tests across multiple operating systems and Python versions.

```yaml
# GitHub Actions workflow
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.11", "3.12"]

    steps:
    - uses: actions/checkout@v4
    - name: Install UV
      uses: astral-sh/setup-uv@v2
    - name: Set up Python ${{ matrix.python-version }}
      run: uv python install ${{ matrix.python-version }}
    - name: Install dependencies
      run: uv pip install -e ".[dev]"
    - name: Run tests
      run: uv run pytest --cov=src/modelforge

```

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

### Documentation Tasks

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/v2.1/provider-enhancements/tasks.md

Tasks for creating comprehensive documentation for the new provider enhancements. This includes guides for streaming, retry configuration, and optimizations, as well as updating the API reference with new classes, methods, and examples.

```python
# TASK-023: Create streaming guide
# Basic usage examples
# Advanced streaming patterns
# Error handling
# Best practices

# TASK-024: Create retry configuration guide
# Provider-specific settings
# Rate limit handling
# Retry strategies
# Troubleshooting

# TASK-025: Create optimization guide
# Available optimizations
# Configuration options
# Cost savings examples
# Performance tips

# TASK-026: Update API reference
# Document new classes
# Document new methods
# Add type hints
# Include examples
```

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

### Updating setup.sh for UV

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/tasks.md

This task focuses on modifying the `setup.sh` script to incorporate UV for dependency management. It includes ensuring UV is installed, creating virtual environments using UV, and installing project dependencies based on the `uv.lock` file.

```shell
# Example setup.sh snippet for UV integration

#!/bin/bash

# Ensure UV is installed or install it
if ! command -v uv &> /dev/null
then
    echo "UV not found. Installing UV..."
    curl -LsSf https://astral.sh/uv/install.sh | sh
    export PATH="$HOME/.uv/bin:$PATH"
fi

# Create virtual environment using UV
UV_LOG_LEVEL=INFO uv venv --python python3 --seed --quiet
source .venv/bin/activate

# Install dependencies from uv.lock
UV_LOG_LEVEL=INFO uv pip sync --frozen

echo "Setup complete. Virtual environment created and dependencies installed."

```

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

### Enhanced Telemetry Callback for LLM Events

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/v2.1/opentelemetry-integration/design.md

Shows an example of an enhanced LangChain callback handler that integrates with OpenTelemetry. It starts a span when an LLM invocation begins and adds token usage and cost attributes when the invocation ends.

```python
from opentelemetry import trace
from langchain.callbacks.base import BaseCallbackHandler
from langchain_core.outputs import LLMResult

# Assume tracer and is_otel_available() are defined elsewhere
tracer = trace.get_tracer(__name__)
def is_otel_available(): return True # Placeholder

class TelemetryCallback(BaseCallbackHandler):
    def __init__(self, provider: str, model: str, otel_enabled: bool = None):
        # Auto-detect if not specified
        self.otel_enabled = otel_enabled or is_otel_available()
        self.span = None
        self.provider = provider
        self.model = model

    def on_llm_start(self, serialized: dict, prompts: list[str], **kwargs):
        if self.otel_enabled:
            self.span = tracer.start_span("langchain.llm.invoke")
            self.span.set_attribute("llm.vendor", self.provider)
            self.span.set_attribute("llm.request.model", self.model)

    def on_llm_end(self, response: LLMResult, **kwargs):
        if self.span:
            # Example attributes, actual values would come from response or context
            prompt_tokens = response.llm_output.get('token_usage', {}).get('prompt_tokens', 0)
            completion_tokens = response.llm_output.get('token_usage', {}).get('completion_tokens', 0)
            total_tokens = prompt_tokens + completion_tokens
            cost = response.llm_output.get('cost_usd', 0.0)

            # Add token usage and cost
            self.span.set_attribute("llm.usage.prompt_tokens", prompt_tokens)
            self.span.set_attribute("llm.usage.completion_tokens", completion_tokens)
            self.span.set_attribute("llm.usage.total_tokens", total_tokens)
            self.span.set_attribute("llm.usage.cost_usd", cost)
            self.span.end()
```

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

### Discover Available Providers

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/BROWSER_PILOT_INTEGRATION.md

Retrieves a list of all LLM providers available from the models.dev repository. It iterates through the list and prints the display name, description, and supported authentication types for each provider.

```python
from modelforge.registry import ModelForgeRegistry

registry = ModelForgeRegistry()

# Get all available providers from models.dev
providers = registry.get_available_providers()
for provider in providers:
    print(f"{provider['display_name']}: {provider['description']}")
    print(f"  Auth types: {provider['auth_types']}")
```

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

### UV Installation Script

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/uv-migration/design.md

Provides the bash commands to install UV using the official installation script and verify the installation.

```bash
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version

```

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

### PyPI Installation Command

Source: https://github.com/smiao-icims/model-forge/blob/main/specs/enhancements/distribution-packaging/tasks.md

Command to install the model-forge-llm package from PyPI.

```bash
pip install model-forge-llm
```

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

### Installation and Upgrade Command

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/v2.2-release-notes.md

Provides the command to install or upgrade the model-forge-llm package to the latest version.

```bash
pip install --upgrade model-forge-llm
```

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

### ModelForge Common Commands

Source: https://github.com/smiao-icims/model-forge/blob/main/README.md

A comprehensive list of common ModelForge CLI commands covering installation, configuration, model management, authentication, testing, and maintenance.

```bash
# Installation & Setup
modelforge --help                                   # Verify installation
modelforge config show                             # View current config

# Model Discovery & Selection
modelforge models list                             # List all available models
modelforge models search "claude"                   # Search models by name
modelforge models info --provider openai --model gpt-4o  # Get model details

# Authentication Management
modelforge auth login --provider openai --api-key KEY   # API key auth
modelforge auth login --provider github_copilot         # Device flow auth
modelforge auth status                                 # Check auth status
modelforge auth logout --provider openai               # Remove credentials

# Configuration Management
modelforge config add --provider openai --model gpt-4o-mini --api-key KEY
modelforge config add --provider ollama --model qwen3:1.7b --local
modelforge config use --provider openai --model gpt-4o-mini
modelforge config remove --provider openai --model gpt-4o-mini

# Testing & Usage (NEW in v2.2: Quiet mode for automation)
modelforge test --prompt "Hello, how are you?"        # Test current model
modelforge test --prompt "Explain quantum computing" --verbose  # Debug mode
modelforge test --input-file prompt.txt --output-file response.txt  # File I/O
echo "What is AI?" | modelforge test                 # Stdin input
modelforge test --prompt "Hello" --no-telemetry      # Disable telemetry
modelforge test --prompt "What is 2+2?" --quiet      # Minimal output (v2.2)
echo "Hello" | modelforge test --quiet > output.txt  # Perfect for piping

# Cache & Maintenance
modelforge models list --refresh                     # Force refresh from models.dev

# Telemetry Settings (NEW in v2.0)
modelforge settings telemetry on                      # Enable telemetry display
modelforge settings telemetry off                     # Disable telemetry display
modelforge settings telemetry status                  # Check current setting
```

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

### Install or Upgrade ModelForge

Source: https://github.com/smiao-icims/model-forge/blob/main/docs/RELEASE_NOTES_v2.3.0.md

This command installs the ModelForge package or upgrades it to the latest version using pip.

```bash
pip install --upgrade model-forge-llm
```

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

### Release Checklist: Run Tests

Source: https://github.com/smiao-icims/model-forge/blob/main/PUBLISHING.md

Executes the project's tests using `pytest` with code coverage enabled for the `src/modelforge` module.

```bash
uv run pytest --cov=src/modelforge
```