examples/custom_clients.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Custom Clients"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from pprint import pprint as pp\n",
    "\n",
    "os.environ[\"LOG_LEVEL\"] = \"debug\"\n",
    "\n",
    "LANGGATE_URL = \"http://localhost:4000/api/v1\"\n",
    "\n",
    "# If running the langgate server behind Envoy proxy in docker:\n",
    "# LANGGATE_URL = \"http://localhost:10000/api/v1\"\n",
    "\n",
    "# If running and accessing langgate from within a kubernetes cluster:\n",
    "# LANGGATE_URL = \"http://langgate.ns.svc.cluster.local:10000/api/v1\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom Local Registry Client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# If you wan to set a custom config file:\n",
    "# os.environ[\"LANGGATE_CONFIG\"] = \"some_custom_path/langgate_config.yaml\"\n",
    "# os.environ[\"LANGGATE_CONFIG\"] = \"some_custom_path/langgate_config.yaml\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 1: Using the SDK's default local registry client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from langgate.sdk import LangGateLocal\n",
    "\n",
    "# `LangGateLocal.registry` is a singleton\n",
    "client = LangGateLocal()\n",
    "models = await client.list_models()  # returns the default LLMInfo schema list\n",
    "pp(models[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 2: Using the standalone default local registry client\n",
    "The registry can be installed without the SDK if you do not need to use any other SDK features such as transforming paramaters.\n",
    "It can be installed separately with:\n",
    "```bash\n",
    "uv add langgate[registry]\n",
    "```\n",
    "or with pip:\n",
    "```bash\n",
    "pip install langgate[registry]\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "LLMInfo(id='openai/gpt-4o', name='GPT-4o', provider=ModelProvider(id='openai', name='OpenAI', description=None), description='The GPT-4o (omni) model from OpenAI builds upon the GPT-4 series with improved performance and multimodal capabilities. GPT-4o is great for most tasks.', costs=ModelCost(input_cost_per_token=Decimal('0.0000025'), output_cost_per_token=Decimal('0.00001'), input_cost_per_token_batches=Decimal('0.00000125'), output_cost_per_token_batches=Decimal('0.000005'), cache_read_input_token_cost=Decimal('0.00000125'), input_cost_per_image='0.003613'), capabilities=ModelCapabilities(supports_tools=True, supports_parallel_tool_calls=True, supports_vision=True, supports_audio_input=None, supports_audio_output=None, supports_prompt_caching=True, supports_response_schema=True, supports_system_messages=True, supports_tool_choice=True), context_window=ContextWindow(max_input_tokens=128000, max_output_tokens=16384), updated_dt=datetime.datetime(2025, 4, 2, 21, 27, 1, 339331, tzinfo=datetime.timezone.utc))\n"
     ]
    }
   ],
   "source": [
    "from langgate.registry.local import LocalRegistryClient\n",
    "\n",
    "# The concrete `LocalRegistryClient` class is a singleton\n",
    "client = LocalRegistryClient()\n",
    "models = await client.list_models()  # returns the default LLMInfo schema list\n",
    "pp(models[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 3: Subclassing BaseLocalRegistryClient with custom schema"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2025-04-02 22:27:39\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mreusing_registry_singleton    \u001b[0m \u001b[36minitialized\u001b[0m=\u001b[35mTrue\u001b[0m\n",
      "\u001b[2m2025-04-02 22:27:39\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1minitialized_base_local_registry_client\u001b[0m\n",
      "\u001b[2m2025-04-02 22:27:39\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mrefreshed_model_cache         \u001b[0m \u001b[36mmodel_count\u001b[0m=\u001b[35m5\u001b[0m\n",
      "CustomLLMInfo(id='openai/gpt-4o', name='GPT-4o', provider=ModelProvider(id='openai', name='OpenAI', description=None), description='The GPT-4o (omni) model from OpenAI builds upon the GPT-4 series with improved performance and multimodal capabilities. GPT-4o is great for most tasks.', costs=ModelCost(input_cost_per_token=Decimal('0.0000025'), output_cost_per_token=Decimal('0.00001'), input_cost_per_token_batches=Decimal('0.00000125'), output_cost_per_token_batches=Decimal('0.000005'), cache_read_input_token_cost=Decimal('0.00000125'), input_cost_per_image='0.003613'), capabilities=ModelCapabilities(supports_tools=True, supports_parallel_tool_calls=True, supports_vision=True, supports_audio_input=None, supports_audio_output=None, supports_prompt_caching=True, supports_response_schema=True, supports_system_messages=True, supports_tool_choice=True), context_window=ContextWindow(max_input_tokens=128000, max_output_tokens=16384), updated_dt=datetime.datetime(2025, 4, 2, 21, 27, 1, 339331, tzinfo=datetime.timezone.utc), extra_field='', custom_metadata={})\n"
     ]
    }
   ],
   "source": [
    "from langgate.registry.local import BaseLocalRegistryClient\n",
    "from langgate.core.models import LLMInfo\n",
    "\n",
    "\n",
    "class CustomLLMInfo(LLMInfo):\n",
    "    extra_field: str = \"\"\n",
    "    custom_metadata: dict = {}\n",
    "\n",
    "\n",
    "class CustomLocalRegistryClient(BaseLocalRegistryClient[CustomLLMInfo]):\n",
    "    \"\"\"Custom Local registry client with CustomLLMInfo schema.\"\"\"\n",
    "\n",
    "    # This is not a singleton unless you implement it as such.\n",
    "\n",
    "\n",
    "custom_client = CustomLocalRegistryClient()\n",
    "custom_models = (\n",
    "    await custom_client.list_models()\n",
    ")  # Typed and validated as list[CustomLLMInfo]\n",
    "pp(custom_models[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 4: Using the base class directly with type parameter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2025-04-02 22:27:54\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mreusing_registry_singleton    \u001b[0m \u001b[36minitialized\u001b[0m=\u001b[35mTrue\u001b[0m\n",
      "\u001b[2m2025-04-02 22:27:54\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1minitialized_base_local_registry_client\u001b[0m\n",
      "\u001b[2m2025-04-02 22:27:54\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mrefreshed_model_cache         \u001b[0m \u001b[36mmodel_count\u001b[0m=\u001b[35m5\u001b[0m\n",
      "CustomLLMInfo(id='openai/gpt-4o', name='GPT-4o', provider=ModelProvider(id='openai', name='OpenAI', description=None), description='The GPT-4o (omni) model from OpenAI builds upon the GPT-4 series with improved performance and multimodal capabilities. GPT-4o is great for most tasks.', costs=ModelCost(input_cost_per_token=Decimal('0.0000025'), output_cost_per_token=Decimal('0.00001'), input_cost_per_token_batches=Decimal('0.00000125'), output_cost_per_token_batches=Decimal('0.000005'), cache_read_input_token_cost=Decimal('0.00000125'), input_cost_per_image='0.003613'), capabilities=ModelCapabilities(supports_tools=True, supports_parallel_tool_calls=True, supports_vision=True, supports_audio_input=None, supports_audio_output=None, supports_prompt_caching=True, supports_response_schema=True, supports_system_messages=True, supports_tool_choice=True), context_window=ContextWindow(max_input_tokens=128000, max_output_tokens=16384), updated_dt=datetime.datetime(2025, 4, 2, 21, 27, 1, 339331, tzinfo=datetime.timezone.utc), extra_field='', custom_metadata={})\n"
     ]
    }
   ],
   "source": [
    "# This is not a singleton.\n",
    "local_client_with_custom_schema = BaseLocalRegistryClient[CustomLLMInfo](\n",
    "    model_info_cls=CustomLLMInfo\n",
    ")\n",
    "direct_models = (\n",
    "    await local_client_with_custom_schema.list_models()\n",
    ")  # Typed and validated as list[CustomLLMInfo]\n",
    "\n",
    "pp(direct_models[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom HTTP Registry Client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pydantic import SecretStr\n",
    "\n",
    "# Optional: Set API key (if your LangGate service requires authentication)\n",
    "api_key = SecretStr(\"your_api_key\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 1: Using the default http client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2025-04-02 19:14:21\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mrefreshed_model_cache         \u001b[0m \u001b[36mmodel_count\u001b[0m=\u001b[35m34\u001b[0m\n",
      "LLMInfo(id='openai/gpt-4o', name='GPT-4o', provider=ModelProvider(id='openai', name='OpenAI', description=None), description='The GPT-4o (omni) model from OpenAI builds upon the GPT-4 series with improved performance and multimodal capabilities. GPT-4o is great for most tasks.', costs=ModelCost(input_cost_per_token=Decimal('0.0000025'), output_cost_per_token=Decimal('0.00001'), input_cost_per_token_batches=Decimal('0.00000125'), output_cost_per_token_batches=Decimal('0.000005'), cache_read_input_token_cost=Decimal('0.00000125'), input_cost_per_image='0.003613'), capabilities=ModelCapabilities(supports_tools=True, supports_parallel_tool_calls=True, supports_vision=True, supports_audio_input=None, supports_audio_output=None, supports_prompt_caching=True, supports_response_schema=True, supports_system_messages=True, supports_tool_choice=True), context_window=ContextWindow(max_input_tokens=128000, max_output_tokens=16384), updated_dt=datetime.datetime(2025, 4, 2, 18, 14, 15, 67814, tzinfo=TzInfo(UTC)))\n"
     ]
    }
   ],
   "source": [
    "from langgate.client.http import HTTPRegistryClient\n",
    "\n",
    "# The concrete `HTTPRegistryClient` class is a singleton\n",
    "client = HTTPRegistryClient(base_url=LANGGATE_URL, api_key=api_key)\n",
    "models = await client.list_models()  # returns the default LLMInfo schema list\n",
    "pp(models[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 2: Subclassing BaseHTTPRegistryClient with custom schema"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2025-04-02 19:14:23\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mrefreshed_model_cache         \u001b[0m \u001b[36mmodel_count\u001b[0m=\u001b[35m34\u001b[0m\n",
      "CustomLLMInfo(id='openai/gpt-4o', name='GPT-4o', provider=ModelProvider(id='openai', name='OpenAI', description=None), description='The GPT-4o (omni) model from OpenAI builds upon the GPT-4 series with improved performance and multimodal capabilities. GPT-4o is great for most tasks.', costs=ModelCost(input_cost_per_token=Decimal('0.0000025'), output_cost_per_token=Decimal('0.00001'), input_cost_per_token_batches=Decimal('0.00000125'), output_cost_per_token_batches=Decimal('0.000005'), cache_read_input_token_cost=Decimal('0.00000125'), input_cost_per_image='0.003613'), capabilities=ModelCapabilities(supports_tools=True, supports_parallel_tool_calls=True, supports_vision=True, supports_audio_input=None, supports_audio_output=None, supports_prompt_caching=True, supports_response_schema=True, supports_system_messages=True, supports_tool_choice=True), context_window=ContextWindow(max_input_tokens=128000, max_output_tokens=16384), updated_dt=datetime.datetime(2025, 4, 2, 18, 14, 15, 67814, tzinfo=TzInfo(UTC)), extra_field='', custom_metadata={})\n"
     ]
    }
   ],
   "source": [
    "from langgate.client.http import BaseHTTPRegistryClient\n",
    "from langgate.core.models import LLMInfo\n",
    "\n",
    "\n",
    "class CustomLLMInfo(LLMInfo):\n",
    "    extra_field: str = \"\"\n",
    "    custom_metadata: dict = {}\n",
    "\n",
    "\n",
    "class CustomHTTPClient(BaseHTTPRegistryClient[CustomLLMInfo]):\n",
    "    \"\"\"Custom HTTP client with CustomLLMInfo schema.\"\"\"\n",
    "\n",
    "    # This is not a singleton unless you implement it as such.\n",
    "\n",
    "\n",
    "custom_client = CustomHTTPClient(LANGGATE_URL, api_key=api_key)\n",
    "custom_models = (\n",
    "    await custom_client.list_models()\n",
    ")  # Typed and validated as list[CustomLLMInfo]\n",
    "pp(custom_models[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example 3: Using the base class directly with type parameter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[2m2025-04-02 19:14:24\u001b[0m [\u001b[32m\u001b[1mdebug    \u001b[0m] \u001b[1mrefreshed_model_cache         \u001b[0m \u001b[36mmodel_count\u001b[0m=\u001b[35m34\u001b[0m\n",
      "CustomLLMInfo(id='openai/gpt-4o', name='GPT-4o', provider=ModelProvider(id='openai', name='OpenAI', description=None), description='The GPT-4o (omni) model from OpenAI builds upon the GPT-4 series with improved performance and multimodal capabilities. GPT-4o is great for most tasks.', costs=ModelCost(input_cost_per_token=Decimal('0.0000025'), output_cost_per_token=Decimal('0.00001'), input_cost_per_token_batches=Decimal('0.00000125'), output_cost_per_token_batches=Decimal('0.000005'), cache_read_input_token_cost=Decimal('0.00000125'), input_cost_per_image='0.003613'), capabilities=ModelCapabilities(supports_tools=True, supports_parallel_tool_calls=True, supports_vision=True, supports_audio_input=None, supports_audio_output=None, supports_prompt_caching=True, supports_response_schema=True, supports_system_messages=True, supports_tool_choice=True), context_window=ContextWindow(max_input_tokens=128000, max_output_tokens=16384), updated_dt=datetime.datetime(2025, 4, 2, 18, 14, 15, 67814, tzinfo=TzInfo(UTC)), extra_field='', custom_metadata={})\n"
     ]
    }
   ],
   "source": [
    "# This is not a singleton.\n",
    "client_with_custom_schema = BaseHTTPRegistryClient[CustomLLMInfo](\n",
    "    base_url=LANGGATE_URL, api_key=api_key, model_info_cls=CustomLLMInfo\n",
    ")\n",
    "direct_models = (\n",
    "    await client_with_custom_schema.list_models()\n",
    ")  # Typed and validated as list[CustomLLMInfo]\n",
    "\n",
    "pp(direct_models[0])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}