RFC: Syntax for ai-models

[AggressivelyMeows]

RFC: Naming conventions for the Drivly AI layer

Summary

We need to unify our naming scheme to allow enterprise customers to easily use our AI tools in their business applications.

Detailed Design

Based on exploration of various approaches, we propose adopting a unified naming convention for AI models that allows for flexible configuration while maintaining compatibility with existing systems.

Model Naming Convention

The naming convention follows this pattern:

{provider}/{creator}/{model}:{capabilities,tools,etc}

Or the simplified form without provider:

{creator or provider}/{model}:{capabilities,tools,etc}

Examples:

• @openai/openai/gpt-4o:code,online
• @anthropic/anthropic/claude-3.7-sonnet:reasoning,code,online
• openrouter/deepseek-r1-distill-qwen-32b

System Options Layer

A second layer of "system" options can be added to the end of the model identifier:

{creator}/{model}:{capabilities,tools,etc}(cache:1w, thread:<uuid | string>, timeout:10s, ...)

This allows setting options that are not specific to the model but are needed for the end-user's application. One challenge is that these options would need to be listed for each model in a fallback chain.

Example Model Identifier Parsing:

parseModelIdentifier('frontier:reasoning,code,online(cache:1w,thread:123e4567,timeout:10s)')

{
  "model": "google/gemini-2.0-flash",
  "capabilities": ["reasoning", "code", "online"],
  "cache": "1w",
  "thread": "123e4567",
  "timeout": "10s"
}

parseModelIdentifier('frontier@fastest,cheapest:reasoning,code,online(cache:1w,thread:123e4567,timeout:10s)')

Fallback Chains

Fallback chains specify a list of models to try in order of preference. While the SDK can support this via arrays, defining this in a URL requires an alternative approach. One method is to use the same query parameter name for all models:

?model=openai:gpt-4o:reasoning(cache:1w,thread:123e4567,timeout:10s)
&model=frontier:reasoning(cache:1w,thread:123e4567,timeout:10s)  

Capability Naming Standardization

Many newer models support both "thinking" and "reasoning" capabilities, but model creators have diverged on terminology. Since these represent the same functionality, we should support both terms but standardize on "reasoning" for future use, as this is more common in SDKs and APIs. For backward compatibility, requests specifying "thinking" can be automatically converted to use the "reasoning" capability.

Versioning

Each model has different versioning schemes, and some may not even have any at all. So if we implemented a way to pin to a specific version, we would need to manually update a versions database. While this is possible, it would be a pain to maintain and wouldnt be scalable.

However, we should remap models with a version number in the name ("Claude-3-7-sonnet") to be renamed to remove the dash between the version numbers. This would make it universal and easier to remember:

• anthropic/claude-3-7-sonnet -> anthropic/claude-3.7-sonnet

Prioritization

• fastest
• cheapest-first
• random