Language Model API¶

Access VS Code's Language Model API to interact with GitHub Copilot and other AI models directly from Python.

Overview¶

The Language Model API enables Python scripts to: - Query available language models (Copilot, custom providers) - Send chat requests with conversation history - Generate code, documentation, and explanations - Count tokens for cost estimation - Build AI-powered automation workflows

LanguageModel ¶

LanguageModel(client: VSCodeClient)

Language Model API for interacting with Copilot and other LLMs.

This class provides access to VS Code's Language Model API, allowing Python scripts to select and interact with available language models.

Initialize the language model API.

Parameters:

Name	Type	Description	Default
`client`	`VSCodeClient`	VSCode client instance	required

Source code in vscode_sockpuppet/language_model.py

def __init__(self, client: "VSCodeClient"):
    """
    Initialize the language model API.

    Args:
        client: VSCode client instance
    """
    self.client = client

select_chat_models ¶

select_chat_models(vendor: Optional[str] = None, family: Optional[str] = None, version: Optional[str] = None, id: Optional[str] = None) -> List[LanguageModelChat]

Select language models matching the given criteria.

Parameters:

Name	Type	Description	Default
`vendor`	`Optional[str]`	Filter by vendor (e.g., 'copilot')	`None`
`family`	`Optional[str]`	Filter by model family (e.g., 'gpt-4o')	`None`
`version`	`Optional[str]`	Filter by version	`None`
`id`	`Optional[str]`	Filter by specific model ID	`None`

Returns:

Type	Description
`List[LanguageModelChat]`	List of matching language models

Raises:

Type	Description
`Exception`	If no models match the criteria or models not available

Example

Get all Copilot models¶

models = client.lm.select_chat_models(vendor='copilot')

Get specific model family¶

models = client.lm.select_chat_models( vendor='copilot', family='gpt-4o' )

Get specific model by ID¶

models = client.lm.select_chat_models( id='copilot-gpt-4o' )

Source code in vscode_sockpuppet/language_model.py

def select_chat_models(
    self,
    vendor: Optional[str] = None,
    family: Optional[str] = None,
    version: Optional[str] = None,
    id: Optional[str] = None,
) -> List[LanguageModelChat]:
    """
    Select language models matching the given criteria.

    Args:
        vendor: Filter by vendor (e.g., 'copilot')
        family: Filter by model family (e.g., 'gpt-4o')
        version: Filter by version
        id: Filter by specific model ID

    Returns:
        List of matching language models

    Raises:
        Exception: If no models match the criteria or models not available

    Example:
        # Get all Copilot models
        models = client.lm.select_chat_models(vendor='copilot')

        # Get specific model family
        models = client.lm.select_chat_models(
            vendor='copilot',
            family='gpt-4o'
        )

        # Get specific model by ID
        models = client.lm.select_chat_models(
            id='copilot-gpt-4o'
        )
    """
    selector = {}
    if vendor is not None:
        selector["vendor"] = vendor
    if family is not None:
        selector["family"] = family
    if version is not None:
        selector["version"] = version
    if id is not None:
        selector["id"] = id

    models_data = self.client._send_request("lm.selectChatModels", {"selector": selector})
    return [LanguageModelChat(self.client, model_data) for model_data in models_data]

LanguageModelChat ¶

LanguageModelChat(client: VSCodeClient, model_data: Dict[str, Any])

Represents a language model for making chat requests.

Initialize a language model.

Parameters:

Name	Type	Description	Default
`client`	`VSCodeClient`	VSCode client instance	required
`model_data`	`Dict[str, Any]`	Model metadata from VS Code	required

Source code in vscode_sockpuppet/language_model.py

def __init__(self, client: "VSCodeClient", model_data: Dict[str, Any]):
    """
    Initialize a language model.

    Args:
        client: VSCode client instance
        model_data: Model metadata from VS Code
    """
    self.client = client
    self._id = model_data["id"]
    self._name = model_data["name"]
    self._vendor = model_data["vendor"]
    self._family = model_data["family"]
    self._version = model_data["version"]
    self._max_input_tokens = model_data["maxInputTokens"]

id `property` ¶

id: str

Unique identifier of the language model.

name `property` ¶

name: str

Human-readable name of the model.

vendor `property` ¶

vendor: str

Vendor of the model (e.g., 'copilot').

family `property` ¶

family: str

Model family (e.g., 'gpt-4o', 'gpt-3.5-turbo').

version `property` ¶

version: str

Model version.

max_input_tokens `property` ¶

max_input_tokens: int

Maximum number of input tokens the model supports.

send_request ¶

send_request(messages: List[LanguageModelChatMessage], options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]

Send a chat request to the language model.

Parameters:

Name	Type	Description	Default
`messages`	`List[LanguageModelChatMessage]`	List of chat messages	required
`options`	`Optional[Dict[str, Any]]`	Optional request options (e.g., temperature, top_p)	`None`

Returns:

Type	Description
`Dict[str, Any]`	Response dictionary with 'text' (full response) and
`Dict[str, Any]`	'parts' (individual fragments)

Raises:

Type	Description
`Exception`	If the model is not available or request fails

Example

messages = [ LanguageModelChatMessage.user("Explain async/await") ] response = model.send_request(messages) print(response['text'])

Source code in vscode_sockpuppet/language_model.py

def send_request(
    self,
    messages: List[LanguageModelChatMessage],
    options: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
    """
    Send a chat request to the language model.

    Args:
        messages: List of chat messages
        options: Optional request options (e.g., temperature, top_p)

    Returns:
        Response dictionary with 'text' (full response) and
        'parts' (individual fragments)

    Raises:
        Exception: If the model is not available or request fails

    Example:
        messages = [
            LanguageModelChatMessage.user("Explain async/await")
        ]
        response = model.send_request(messages)
        print(response['text'])
    """
    message_dicts = [msg.to_dict() for msg in messages]
    return self.client._send_request(
        "lm.sendRequest",
        {
            "modelId": self._id,
            "messages": message_dicts,
            "options": options or {},
        },
    )

count_tokens ¶

count_tokens(text: str) -> int

Count the number of tokens in a text string.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to count tokens for	required

Returns:

Type	Description
`int`	Number of tokens

Example

tokens = model.count_tokens("Hello, world!") print(f"Token count: {tokens}")

Source code in vscode_sockpuppet/language_model.py

def count_tokens(self, text: str) -> int:
    """
    Count the number of tokens in a text string.

    Args:
        text: The text to count tokens for

    Returns:
        Number of tokens

    Example:
        tokens = model.count_tokens("Hello, world!")
        print(f"Token count: {tokens}")
    """
    return self.client._send_request("lm.countTokens", {"modelId": self._id, "text": text})

repr ¶

__repr__() -> str

String representation of the model.

Source code in vscode_sockpuppet/language_model.py

def __repr__(self) -> str:
    """String representation of the model."""
    return (
        f"LanguageModelChat(id={self._id!r}, vendor={self._vendor!r}, family={self._family!r})"
    )

LanguageModelChatMessage ¶

LanguageModelChatMessage(role: str, content: str)

Represents a chat message for language model requests.

Create a chat message.

Parameters:

Name	Type	Description	Default
`role`	`str`	Message role ('user' or 'assistant')	required
`content`	`str`	Message content	required

Source code in vscode_sockpuppet/language_model.py

def __init__(self, role: str, content: str):
    """
    Create a chat message.

    Args:
        role: Message role ('user' or 'assistant')
        content: Message content
    """
    self.role = role
    self.content = content

user `classmethod` ¶

user(content: str) -> LanguageModelChatMessage

Create a user message.

Parameters:

Name	Type	Description	Default
`content`	`str`	The user's message content	required

Returns:

Type	Description
`LanguageModelChatMessage`	A chat message with role 'user'

Example

msg = LanguageModelChatMessage.user("Explain this code")

Source code in vscode_sockpuppet/language_model.py

@classmethod
def user(cls, content: str) -> "LanguageModelChatMessage":
    """
    Create a user message.

    Args:
        content: The user's message content

    Returns:
        A chat message with role 'user'

    Example:
        msg = LanguageModelChatMessage.user("Explain this code")
    """
    return cls("user", content)

assistant `classmethod` ¶

assistant(content: str) -> LanguageModelChatMessage

Create an assistant message.

Parameters:

Name	Type	Description	Default
`content`	`str`	The assistant's message content	required

Returns:

Type	Description
`LanguageModelChatMessage`	A chat message with role 'assistant'

Example

msg = LanguageModelChatMessage.assistant("This code...")

Source code in vscode_sockpuppet/language_model.py

@classmethod
def assistant(cls, content: str) -> "LanguageModelChatMessage":
    """
    Create an assistant message.

    Args:
        content: The assistant's message content

    Returns:
        A chat message with role 'assistant'

    Example:
        msg = LanguageModelChatMessage.assistant("This code...")
    """
    return cls("assistant", content)

to_dict ¶

to_dict() -> Dict[str, str]

Convert message to dictionary for JSON serialization.

Source code in vscode_sockpuppet/language_model.py

def to_dict(self) -> Dict[str, str]:
    """Convert message to dictionary for JSON serialization."""
    return {"role": self.role, "content": self.content}

Usage Examples¶

Basic Chat Request¶

from vscode_sockpuppet import VSCodeClient, LanguageModelChatMessage

client = VSCodeClient()
client.connect()

# Get available models
models = client.lm.select_chat_models(vendor='copilot')
model = models[0]

# Send a request
messages = [
    LanguageModelChatMessage.user("Explain async/await in Python")
]

response = model.send_request(messages)
print(response['text'])

Multi-turn Conversation¶

# Start conversation
messages = [
    LanguageModelChatMessage.user("What is a Python decorator?")
]

response = model.send_request(messages)
print(f"Assistant: {response['text']}")

# Add response to history
messages.append(
    LanguageModelChatMessage.assistant(response['text'])
)

# Ask follow-up
messages.append(
    LanguageModelChatMessage.user("Show me an example")
)

response = model.send_request(messages)
print(f"Assistant: {response['text']}")

Code Generation¶

messages = [
    LanguageModelChatMessage.user(
        "Write a Python function to check if a number is prime. "
        "Include docstring and type hints."
    )
]

response = model.send_request(messages)
generated_code = response['text']
print(generated_code)

Token Counting¶

# Count tokens before sending
text = "This is a long piece of text..."
token_count = model.count_tokens(text)
print(f"This will use approximately {token_count} tokens")

# Helpful for estimating costs and staying within limits
if token_count < model.max_input_tokens:
    response = model.send_request([
        LanguageModelChatMessage.user(text)
    ])

Code Explanation Workflow¶

# Get selected code from active editor
editor = client.editor.get_active_text_editor()
if editor and editor.selection:
    doc = client.workspace.open_text_document(editor.document['uri'])
    selected_text = doc.get_text_range(editor.selection)

    # Ask model to explain
    messages = [
        LanguageModelChatMessage.user(
            f"Explain this code:\n\n{selected_text}"
        )
    ]

    response = model.send_request(messages)

    # Show explanation in VS Code
    client.window.show_information_message(
        f"Explanation: {response['text'][:200]}..."
    )

Error Analysis¶

error_code = """
def divide(a, b):
    return a / b
"""

error_message = "ZeroDivisionError: division by zero"

messages = [
    LanguageModelChatMessage.user(
        f"This code has an error:\n\n{error_code}\n\n"
        f"Error: {error_message}\n\n"
        "Explain the problem and suggest a fix."
    )
]

response = model.send_request(messages)
print(response['text'])

Model Selection¶

# Get all available models
all_models = client.lm.select_chat_models()
for model in all_models:
    print(f"{model.name}: {model.max_input_tokens:,} tokens")

# Get specific vendor
copilot_models = client.lm.select_chat_models(vendor='copilot')

# Get specific model family
gpt4_models = client.lm.select_chat_models(
    vendor='copilot',
    family='gpt-4o'
)

# Get by exact ID
specific = client.lm.select_chat_models(
    id='copilot-gpt-4o'
)

Requirements¶

GitHub Copilot¶

To use the Language Model API with Copilot:

Install the GitHub Copilot extension in VS Code
Sign in to your GitHub account
Have an active Copilot subscription

Custom Language Model Providers¶

VS Code's Language Model API supports custom providers. Any extension that implements the LanguageModelChatProvider interface will be accessible through this API.

Error Handling¶

try:
    models = client.lm.select_chat_models(vendor='copilot')

    if not models:
        print("No models available - is Copilot installed?")
        exit(1)

    model = models[0]
    response = model.send_request(messages)

except Exception as e:
    if "LanguageModelError" in str(e):
        print(f"Language model error: {e}")
        # Could be: model not found, user consent not given,
        # quota exceeded, content filtered, etc.
    else:
        print(f"Unexpected error: {e}")

Best Practices¶

1. Check Model Availability¶

models = client.lm.select_chat_models(vendor='copilot')
if not models:
    client.window.show_warning_message(
        "Copilot not available. Please sign in and try again."
    )
    exit(1)

2. Handle Conversation Context¶

# Keep conversation history for context
conversation = []

def ask(question: str) -> str:
    conversation.append(LanguageModelChatMessage.user(question))
    response = model.send_request(conversation)
    answer = response['text']
    conversation.append(LanguageModelChatMessage.assistant(answer))
    return answer

3. Stay Within Token Limits¶

# Check if prompt fits within limits
prompt_tokens = model.count_tokens(user_prompt)
if prompt_tokens > model.max_input_tokens:
    print(f"Prompt too long! {prompt_tokens}/{model.max_input_tokens}")
    # Truncate or split the prompt

4. Provide Clear Instructions¶

# Be specific in your requests
messages = [
    LanguageModelChatMessage.user(
        "Write a Python function that:\n"
        "1. Takes a list of numbers\n"
        "2. Returns only the even numbers\n"
        "3. Includes type hints\n"
        "4. Has a docstring with an example\n"
        "5. Uses list comprehension"
    )
]

Use Cases¶

Documentation Generation¶

Generate docstrings, comments, and README content:

def generate_docstring(function_code: str) -> str:
    messages = [
        LanguageModelChatMessage.user(
            f"Generate a comprehensive Google-style docstring "
            f"for this function:\n\n{function_code}"
        )
    ]
    response = model.send_request(messages)
    return response['text']

Code Review Assistant¶

Analyze code for issues and suggestions:

def review_code(code: str) -> str:
    messages = [
        LanguageModelChatMessage.user(
            f"Review this code for:\n"
            f"- Potential bugs\n"
            f"- Performance issues\n"
            f"- Best practices\n\n"
            f"{code}"
        )
    ]
    response = model.send_request(messages)
    return response['text']

Test Generation¶

Create unit tests automatically:

def generate_tests(function_code: str) -> str:
    messages = [
        LanguageModelChatMessage.user(
            f"Generate pytest unit tests for this function:\n\n"
            f"{function_code}\n\n"
            f"Include edge cases and error conditions."
        )
    ]
    response = model.send_request(messages)
    return response['text']

Refactoring Suggestions¶

Get improvement recommendations:

def suggest_refactoring(code: str) -> str:
    messages = [
        LanguageModelChatMessage.user(
            f"Suggest refactoring improvements for:\n\n{code}\n\n"
            f"Focus on readability and maintainability."
        )
    ]
    response = model.send_request(messages)
    return response['text']

API Reference¶

See the full API documentation for detailed information about:

LanguageModel class and methods
LanguageModelChat properties and operations
LanguageModelChatMessage message construction
Error handling and exceptions
Advanced options and parameters

Language Model API¶

Overview¶

LanguageModel ¶

select_chat_models ¶

Get all Copilot models¶

Get specific model family¶

Get specific model by ID¶

LanguageModelChat ¶

id property ¶

name property ¶

vendor property ¶

family property ¶

version property ¶

max_input_tokens property ¶

send_request ¶

count_tokens ¶

__repr__ ¶

LanguageModelChatMessage ¶

user classmethod ¶

assistant classmethod ¶

to_dict ¶

Usage Examples¶

Basic Chat Request¶

Multi-turn Conversation¶

Code Generation¶

Token Counting¶

Code Explanation Workflow¶

Error Analysis¶

Model Selection¶

Requirements¶

GitHub Copilot¶

Custom Language Model Providers¶

Error Handling¶

Best Practices¶

1. Check Model Availability¶

2. Handle Conversation Context¶

3. Stay Within Token Limits¶

4. Provide Clear Instructions¶

Use Cases¶

Documentation Generation¶

Code Review Assistant¶

Test Generation¶

Refactoring Suggestions¶

API Reference¶

id `property` ¶

name `property` ¶

vendor `property` ¶

family `property` ¶

version `property` ¶

max_input_tokens `property` ¶

repr ¶

user `classmethod` ¶

assistant `classmethod` ¶