Provider Defined Profiles

[mcowger]

Design Proposal: Provider-Defined Integrations

Date: September 7, 2025
Status: Draft

1. Abstract

The current system for adding new AI providers to Kilocode.ai requires manual, hard-coded definitions. As the majority of emerging providers adopt OpenAI-compatible APIs, this has led to significant code duplication and maintenance overhead. Definitions quickly become outdated as providers update models, pricing, and capabilities. This document proposes a new "Provider Defined" integration type, a dynamic mechanism that allows Kilocode to self-configure by fetching a provider's definition directly from a standardized endpoint they host. This approach shifts the responsibility of maintaining up-to-date information to the providers themselves, drastically reducing engineering effort for the Kilocode team and ensuring users always have access to the latest data.

2. Problem Statement

Adding a new provider in Kilocode is currently a manual process. For each new provider, a definition file is created that specifies details such as API endpoints, authentication methods, available models, context limits, and pricing. This has several drawbacks:

• Duplication of Effort: Most new providers are OpenAI-compatible, meaning their definitions are nearly identical, differing only in specific values like base URLs and model lists. This copy-paste approach is inefficient.

• Maintenance Burden: The Kilocode team is responsible for tracking changes across all supported providers. When a provider adds a new model, changes pricing, or updates an endpoint, a manual update and deployment are required.

• Stale Information: Due to the manual update cycle, the provider information within Kilocode can easily become outdated, leading to user confusion and configuration errors.

• Slow Onboarding: The time required to manually add and vet a new provider creates a bottleneck, slowing down the expansion of Kilocode's supported ecosystem.

3. Proposed Solution: The "Provider Defined" Type

To solve these issues, we will introduce a new, virtual integration pattern called the "Provider Defined" type. When a user wishes to add a provider of this type, they will simply provide a single URL. Kilocode will then fetch all necessary configuration details from this URL, dynamically building the provider profile.

This system is composed of two main parts: the Provider Manifest and the Model Data Source.

3.1. Step 1: The Provider Manifest Endpoint

Providers wishing to support this dynamic integration must host a simple JSON endpoint. This endpoint will serve as the initial source of truth, providing basic information about the provider.

• Recommended Endpoint: /v1/models?provider=true

• Method: GET

When a user adds a new 'Provider Defined' configuration, they will enter the full URL to this endpoint (e.g., https://api.synthetic.new/v1/models?provider=true). Kilocode will then fetch and parse the following JSON structure:

{
  "name": "Provider Name",
  "website": "[https://provider.example.com](https://provider.example.com)",
  "baseUrl": "[https://api.provider.example.com/v1](https://api.provider.example.com/v1)",
  "models_dev_provider_id": "provider-id-on-models-dev",
  "models_data_source": "endpoint"
}

name

This is a required text field for the provider's official name, which would be used for display purposes in an application.

• Type: String

• Example: "OpenAI"

---

website

This is a required text field for the provider's main website address.

• Type: String

• Example: "https://www.openai.com"

---

baseUrl

This is a required text field that serves as the foundation for all API requests to the provider. Specific endpoints (like /chat/completions) are appended to this URL.

• Type: String

• Example: "https://api.openai.com/v1"

---

models_dev_provider_id

This is an optional text field containing a unique identifier for the provider on a service called models.dev. This field is only necessary if you intend to fetch the model list from models.dev instead of directly from the provider's API.

• Type: String

• Required: Only if models_data_source is set to models_dev.

---

models_data_source

This is a required field that dictates how the list of available models should be obtained. It acts as a switch with two possible options.

• Type: Enum (Enumeration)

• Values:

  • endpoint: Retrieve the model list by making a call to a specific API endpoint provided by the provider.

  • models_dev: Retrieve the model list from the models.dev service, using the models_dev_provider_id to identify the provider.

3.2. Step 2: Model Information Sourcing

Once the manifest is fetched, Kilocode uses the models_data_source field to determine how to retrieve the complete list of available models and their detailed attributes. We propose two initial methods.

Method 1: endpoint

If a provider sets models_data_source to "endpoint", they commit to hosting and maintaining an extended version of the standard OpenAI /v1/models endpoint. This endpoint will provide rich metadata for each model, similar to the dataset available on models.dev.

• Recommended Endpoint: /v1/models?extended=true

• Method: GET

• Expected Response Structure: A JSON object containing a models key, which maps model IDs to their detailed definitions.

{
  "models": {
    "provider/model-name-v1": {
      "id": "provider/model-name-v1",
      "name": "Model Name V1",
      "attachment": false,
      "reasoning": true,
      "temperature": true,
      "tool_call": true,
      "release_date": "2025-08-21",
      "last_updated": "2025-08-21",
      "modalities": {
        "input": ["text", "image"],
        "output": ["text"]
      },
      "open_weights": false,
      "cost": {
        "input": 0.50,
        "output": 1.50
      },
      "limit": {
        "context": 128000,
        "output": 4096
      }
    },
    "provider/another-model-v2": {
      "id": "provider/another-model-v2",
      "name": "Another Model V2"
    }
  }
}

Method 2: models_dev

For providers who prefer not to maintain their own detailed models endpoint, they can opt to use models.dev (or a future alternative) as the data source.

If a provider sets models_data_source to "models_dev", Kilocode will:

1. Read the models_dev_provider_id from the provider manifest.

2. Query the models.dev public API (e.g., https://models.dev/api.json).

3. Filter the results from the models.dev API to find all models associated with that models_dev_provider_id.

4. Use this filtered list to populate the model information for the provider in Kilocode.

This method allows providers to leverage existing infrastructure and simply ensure their information on models.dev is accurate.

4. User Workflow

The process for the end-user will be remarkably simple:

1. In the Kilocode UI, the user navigates to "Add New Provider."

2. They select the "Provider Defined" type from the list.

3. A single input field appears, asking for the "Provider Definition URL."

4. The user pastes the provider's manifest URL (e.g., https://api.groq.com/openai/v1/models?provider=true).

5. Kilocode fetches the manifest, determines the model data source, and retrieves the model list.

6. The provider, complete with its name, icon (fetched from the website), and available models, is now fully configured and ready for use.

5. Benefits

This approach offers significant advantages over the current system:

• Zero Maintenance: The Kilocode team is no longer responsible for updating provider definitions.

• Empowerment: Providers have direct control over how their service is represented within Kilocode.

• Real-Time Updates: Users get immediate access to new models and pricing changes as soon as the provider updates their endpoint.

• Rapid Integration: New OpenAI-compatible providers can be added to Kilocode by users in seconds, without any code changes from the core team.

• Scalability: This pattern allows Kilocode's ecosystem to grow organically and exponentially without increasing the engineering burden.