gitlab-ai-provider 5.0.0

package/README.md

@@ -0,0 +1,815 @@
+# GitLab AI Provider
+
+A comprehensive TypeScript provider for integrating GitLab Duo AI capabilities with the Vercel AI SDK. This package enables seamless access to GitLab's AI-powered features including chat, agentic workflows, and tool calling through a unified interface.
+
+## 🌟 Features
+
+- **🤖 Multi-Provider Agentic Chat**: Native tool calling support via GitLab's AI Gateway (Anthropic & OpenAI)
+- **🔄 Duo Workflow Service**: Server-side agentic loop with WebSocket streaming and dynamic model discovery
+- **🔐 Multiple Authentication**: Support for OAuth, Personal Access Tokens, and OpenCode auth
+- **🌐 Self-Hosted Support**: Works with both GitLab.com and self-hosted instances
+- **🔧 Tool Support**: Native tool calling via Vercel AI SDK and MCP tools for workflows
+- **🔍 Project Detection**: Automatic GitLab project detection from git remotes
+- **💾 Smart Caching**: Project, token, and model discovery caching for optimal performance
+- **🎯 Type-Safe**: Complete TypeScript definitions with Zod validation
+
+## 📦 Installation
+
+```bash
+npm install gitlab-ai-provider
+```
+
+### Peer Dependencies
+
+```bash
+npm install @ai-sdk/provider @ai-sdk/provider-utils
+```
+
+## 🚀 Quick Start
+
+### Basic Chat
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+import { generateText } from 'ai';
+
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+  instanceUrl: 'https://gitlab.com', // optional, defaults to gitlab.com
+});
+
+// All equivalent ways to create a chat model:
+const model = gitlab('duo-chat'); // callable provider
+const model2 = gitlab.chat('duo-chat'); // .chat() alias (recommended)
+const model3 = gitlab.languageModel('duo-chat'); // explicit method
+
+const { text } = await generateText({
+  model: gitlab.chat('duo-chat'),
+  prompt: 'Explain how to create a merge request in GitLab',
+});
+
+console.log(text);
+```
+
+### Agentic Chat with Tool Calling
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+import { generateText } from 'ai';
+
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+});
+
+// Use agentic model for native tool calling support
+const model = gitlab.agenticChat('duo-chat', {
+  anthropicModel: 'claude-sonnet-4-20250514',
+  maxTokens: 8192,
+});
+
+const { text } = await generateText({
+  model,
+  prompt: 'List all open merge requests in my project',
+  tools: {
+    // Your custom tools here
+  },
+});
+```
+
+### Model Variants
+
+The provider automatically maps specific model IDs to their corresponding provider models (Anthropic or OpenAI) and routes requests to the appropriate AI Gateway proxy:
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+import { generateText } from 'ai';
+
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+});
+
+// Anthropic Models (Claude)
+const opusModel = gitlab.agenticChat('duo-chat-opus-4-5');
+// Automatically uses: claude-opus-4-5-20251101
+
+const sonnetModel = gitlab.agenticChat('duo-chat-sonnet-4-5');
+// Automatically uses: claude-sonnet-4-5-20250929
+
+const haikuModel = gitlab.agenticChat('duo-chat-haiku-4-5');
+// Automatically uses: claude-haiku-4-5-20251001
+
+// OpenAI Models (GPT-5)
+const gpt5Model = gitlab.agenticChat('duo-chat-gpt-5-1');
+// Automatically uses: gpt-5.1-2025-11-13
+
+const gpt5MiniModel = gitlab.agenticChat('duo-chat-gpt-5-mini');
+// Automatically uses: gpt-5-mini-2025-08-07
+
+const codexModel = gitlab.agenticChat('duo-chat-gpt-5-codex');
+// Automatically uses: gpt-5-codex
+
+// You can still override with explicit providerModel option
+const customModel = gitlab.agenticChat('duo-chat-opus-4-5', {
+  providerModel: 'claude-sonnet-4-5-20250929', // Override mapping
+});
+```
+
+**Available Model Mappings:**
+
+| Model ID                 | Provider  | Backend Model                |
+| ------------------------ | --------- | ---------------------------- |
+| `duo-chat-opus-4-5`      | Anthropic | `claude-opus-4-5-20251101`   |
+| `duo-chat-sonnet-4-5`    | Anthropic | `claude-sonnet-4-5-20250929` |
+| `duo-chat-haiku-4-5`     | Anthropic | `claude-haiku-4-5-20251001`  |
+| `duo-chat-gpt-5-1`       | OpenAI    | `gpt-5.1-2025-11-13`         |
+| `duo-chat-gpt-5-mini`    | OpenAI    | `gpt-5-mini-2025-08-07`      |
+| `duo-chat-gpt-5-codex`   | OpenAI    | `gpt-5-codex`                |
+| `duo-chat-gpt-5-2-codex` | OpenAI    | `gpt-5.2-codex`              |
+
+For unmapped Anthropic model IDs, the provider defaults to `claude-sonnet-4-5-20250929`.
+
+### OpenAI Models (GPT-5)
+
+The provider supports OpenAI GPT-5 models through GitLab's AI Gateway proxy. OpenAI models are automatically detected based on the model ID and routed to the appropriate proxy endpoint.
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+import { generateText } from 'ai';
+
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+});
+
+// GPT-5.1 - Most capable model
+const { text } = await generateText({
+  model: gitlab.agenticChat('duo-chat-gpt-5-1'),
+  prompt: 'Explain GitLab CI/CD pipelines',
+});
+
+// GPT-5 Mini - Fast and efficient
+const { text: quickResponse } = await generateText({
+  model: gitlab.agenticChat('duo-chat-gpt-5-mini'),
+  prompt: 'Summarize this code',
+});
+
+// GPT-5 Codex - Optimized for code
+const { text: codeExplanation } = await generateText({
+  model: gitlab.agenticChat('duo-chat-gpt-5-codex'),
+  prompt: 'Refactor this function for better performance',
+});
+```
+
+**OpenAI Models with Tool Calling:**
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+import { generateText, tool } from 'ai';
+import { z } from 'zod';
+
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+});
+
+const { text, toolCalls } = await generateText({
+  model: gitlab.agenticChat('duo-chat-gpt-5-1', {
+    maxTokens: 4096,
+  }),
+  prompt: 'What is the weather in San Francisco?',
+  tools: {
+    getWeather: tool({
+      description: 'Get the weather for a location',
+      parameters: z.object({
+        location: z.string().describe('The city name'),
+      }),
+      execute: async ({ location }) => {
+        return { temperature: 72, condition: 'sunny', location };
+      },
+    }),
+  },
+});
+```
+
+### Agentic Chat with Feature Flags
+
+You can pass feature flags to enable experimental features in GitLab's AI Gateway proxy:
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+
+// Option 1: Set feature flags globally for all agentic chat models
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+  featureFlags: {
+    duo_agent_platform_agentic_chat: true,
+    duo_agent_platform: true,
+  },
+});
+
+const model = gitlab.agenticChat('duo-chat');
+
+// Option 2: Set feature flags per model (overrides global flags)
+const modelWithFlags = gitlab.agenticChat('duo-chat', {
+  featureFlags: {
+    duo_agent_platform_agentic_chat: true,
+    duo_agent_platform: true,
+    custom_feature_flag: false,
+  },
+});
+
+// Option 3: Merge both (model-level flags take precedence)
+const gitlab2 = createGitLab({
+  featureFlags: {
+    duo_agent_platform: true, // will be overridden
+  },
+});
+
+const mergedModel = gitlab2.agenticChat('duo-chat', {
+  featureFlags: {
+    duo_agent_platform: false, // overrides provider-level
+    duo_agent_platform_agentic_chat: true, // adds new flag
+  },
+});
+```
+
+### Duo Workflow Service (Server-Side Agentic)
+
+The Duo Workflow Service provides a server-side agentic loop where GitLab drives the LLM and streams tool execution requests to the client via WebSocket. This enables powerful agentic workflows with dynamic model discovery and MCP tool integration.
+
+**Requirements:**
+
+- GitLab Ultimate with Duo Enterprise add-on
+- GitLab 18.4+ (18.5+ for pinned model support)
+
+```typescript
+import { createGitLab } from 'gitlab-ai-provider';
+import { streamText } from 'ai';
+
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+  instanceUrl: 'https://gitlab.com', // or your self-hosted instance
+});
+
+// Use the duo-workflow model for server-side agentic workflows
+const model = gitlab.workflowChat('duo-workflow', {
+  // Optional: Specify root namespace for model discovery
+  rootNamespaceId: 'gid://gitlab/Group/12345',
+
+  // Optional: Provide MCP tools for the workflow
+  mcpTools: [
+    {
+      name: 'searchCode',
+      description: 'Search for code in the repository',
+      inputSchema: JSON.stringify({
+        type: 'object',
+        properties: {
+          query: { type: 'string' },
+        },
+        required: ['query'],
+      }),
+    },
+  ],
+
+  // Optional: Pre-approve tools for automatic execution
+  preapprovedTools: ['read_file', 'write_file'],
+});
+
+// Stream the workflow execution
+const result = await streamText({
+  model,
+  prompt: 'Refactor the authentication module to use JWT tokens',
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+**Dynamic Model Discovery:**
+
+The workflow service automatically discovers available models for your namespace and respects admin-pinned models:
+
+```typescript
+const model = gitlab.workflowChat('duo-workflow', {
+  rootNamespaceId: 'gid://gitlab/Group/12345',
+
+  // Optional: Callback for interactive model selection
+  onSelectModel: async (models) => {
+    // Present model picker to user
+    console.log('Available models:', models);
+    // Return selected model ref or null for default
+    return models[0].ref;
+  },
+});
+```
+
+**Model Selection Priority:**
+
+1. Admin-pinned model (always used if set)
+2. User-selected model (via `onSelectModel` callback)
+3. Namespace default model
+
+**Built-in Tool Support:**
+
+The workflow service automatically maps DWS built-in tools to consumer tool names:
+
+| DWS Tool          | Consumer Tool | Description                   |
+| ----------------- | ------------- | ----------------------------- |
+| `runReadFile`     | `read`        | Read file contents            |
+| `runWriteFile`    | `write`       | Write file contents           |
+| `runEditFile`     | `edit`        | Edit file with old/new string |
+| `runShellCommand` | `bash`        | Execute shell command         |
+| `runCommand`      | `bash`        | Execute structured command    |
+| `runGitCommand`   | `bash`        | Execute git command           |
+| `listDirectory`   | `read`        | List directory contents       |
+| `findFiles`       | `glob`        | Find files by pattern         |
+| `grep`            | `grep`        | Search file contents          |
+| `mkdir`           | `bash`        | Create directory              |
+| `runHTTPRequest`  | `bash`        | Execute HTTP request          |
+
+**Workflow Options:**
+
+```typescript
+interface GitLabWorkflowOptions {
+  // Root namespace ID for model discovery and token scoping
+  rootNamespaceId?: string;
+
+  // GitLab project ID (numeric or path)
+  projectId?: string;
+
+  // GitLab namespace ID
+  namespaceId?: string;
+
+  // MCP tool definitions to expose to the workflow
+  mcpTools?: McpToolDefinition[];
+
+  // Client capabilities to advertise
+  clientCapabilities?: string[]; // Default: ['shell_command']
+
+  // Tool names pre-approved for execution without confirmation
+  preapprovedTools?: string[];
+
+  // Additional context items for conversation history
+  additionalContext?: AdditionalContext[];
+
+  // Feature flags for the workflow
+  featureFlags?: Record<string, boolean>;
+
+  // Working directory for project auto-detection
+  workingDirectory?: string; // Default: process.cwd()
+
+  // Flow configuration for agent behavior
+  flowConfig?: unknown;
+
+  // Flow configuration schema version
+  flowConfigSchemaVersion?: string;
+
+  // Callback for interactive model selection
+  onSelectModel?: (models: AiModel[]) => Promise<string | null | undefined>;
+}
+```
+
+**Environment Variables:**
+
+| Variable              | Description                                 | Default              |
+| --------------------- | ------------------------------------------- | -------------------- |
+| `GITLAB_INSTANCE_URL` | GitLab instance URL                         | `https://gitlab.com` |
+| `GITLAB_TOKEN`        | GitLab Personal Access Token or OAuth token | -                    |
+
+**Model Cache:**
+
+The workflow service caches model discovery results and user selections in `~/.cache/opencode/gitlab-workflow-model-cache.json` (or `$XDG_CACHE_HOME/opencode/...`). The cache is keyed by workspace directory and instance URL, with a 10-minute TTL for discovery data.
+
+## 🔑 Authentication
+
+### Personal Access Token
+
+```typescript
+const gitlab = createGitLab({
+  apiKey: 'glpat-xxxxxxxxxxxxxxxxxxxx',
+});
+```
+
+### Environment Variable
+
+```bash
+export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+```
+
+```typescript
+const gitlab = createGitLab(); // Automatically uses GITLAB_TOKEN
+```
+
+### OAuth (OpenCode Auth)
+
+The provider automatically detects and uses OpenCode authentication if available:
+
+```typescript
+const gitlab = createGitLab({
+  instanceUrl: 'https://gitlab.com',
+  // OAuth tokens are loaded from ~/.opencode/auth.json
+});
+```
+
+### Custom Headers
+
+```typescript
+const gitlab = createGitLab({
+  apiKey: 'your-token',
+  headers: {
+    'X-Custom-Header': 'value',
+  },
+});
+```
+
+### AI Gateway Headers
+
+Custom headers can be sent to GitLab's AI Gateway (Anthropic/OpenAI proxy) for traffic identification and routing. By default, the provider sends `User-Agent: gitlab-ai-provider/{version}`.
+
+```typescript
+// Provider-level headers (apply to all agentic models)
+const gitlab = createGitLab({
+  apiKey: process.env.GITLAB_TOKEN,
+  aiGatewayHeaders: {
+    'X-Custom-Routing': 'premium-tier',
+  },
+});
+
+// Model-level headers (override provider-level)
+const model = gitlab.agenticChat('duo-chat-opus-4-5', {
+  aiGatewayHeaders: {
+    'X-Request-Priority': 'high',
+  },
+});
+```
+
+**Header Precedence (lowest to highest):**
+
+1. Default headers (`User-Agent: gitlab-ai-provider/{version}`)
+2. Provider-level `aiGatewayHeaders`
+3. Model-level `aiGatewayHeaders`
+
+## 🏗️ Architecture
+
+### Core Components
+
+#### 1. **GitLabProvider**
+
+Main provider factory that creates language models with different capabilities.
+
+```typescript
+interface GitLabProvider {
+  (modelId: string): LanguageModelV2;
+  languageModel(modelId: string): LanguageModelV2;
+  agenticChat(modelId: string, options?: GitLabAgenticOptions): GitLabAgenticLanguageModel;
+  workflowChat(modelId: string, options?: GitLabWorkflowOptions): GitLabWorkflowLanguageModel;
+}
+```
+
+#### 2. **GitLabAnthropicLanguageModel**
+
+Provides native tool calling through GitLab's Anthropic proxy.
+
+- Uses Claude models via `https://cloud.gitlab.com/ai/v1/proxy/anthropic/`
+- Automatic token refresh and retry logic
+- Direct access token management
+- Supports all Anthropic tool calling features
+
+#### 3. **GitLabOpenAILanguageModel**
+
+Provides native tool calling through GitLab's OpenAI proxy.
+
+- Uses GPT-5 models via `https://cloud.gitlab.com/ai/v1/proxy/openai/`
+- Automatic token refresh and retry logic
+- Direct access token management
+- Supports all OpenAI tool calling features including parallel tool calls
+
+#### 4. **GitLabWorkflowLanguageModel**
+
+Provides server-side agentic execution through GitLab Duo Workflow Service.
+
+- WebSocket-based bidirectional communication with DWS
+- Dynamic model discovery via GraphQL (`aiChatAvailableModels`)
+- Automatic model selection (pinned → user-selected → default)
+- Built-in tool mapping and MCP tool support
+- Per-stream state isolation for concurrent requests
+- Dual heartbeat (WebSocket ping + JSON heartbeat)
+
+### Supporting Utilities
+
+#### GitLabProjectDetector
+
+Automatically detects GitLab projects from git remotes.
+
+```typescript
+const detector = new GitLabProjectDetector({
+  instanceUrl: 'https://gitlab.com',
+  getHeaders: () => ({ Authorization: `Bearer ${token}` }),
+});
+
+const project = await detector.detectProject(process.cwd());
+// Returns: { id: 12345, path: 'group/project', namespaceId: 67890 }
+```
+
+#### GitLabProjectCache
+
+Caches project information with TTL.
+
+```typescript
+const cache = new GitLabProjectCache(5 * 60 * 1000); // 5 minutes
+cache.set('key', project);
+const cached = cache.get('key');
+```
+
+#### GitLabOAuthManager
+
+Manages OAuth token lifecycle.
+
+```typescript
+const oauthManager = new GitLabOAuthManager();
+
+// Exchange authorization code
+const tokens = await oauthManager.exchangeAuthorizationCode({
+  instanceUrl: 'https://gitlab.com',
+  code: 'auth-code',
+  codeVerifier: 'verifier',
+});
+
+// Refresh tokens
+const refreshed = await oauthManager.refreshIfNeeded(tokens);
+```
+
+#### GitLabDirectAccessClient
+
+Manages direct access tokens for Anthropic proxy.
+
+```typescript
+const client = new GitLabDirectAccessClient({
+  instanceUrl: 'https://gitlab.com',
+  getHeaders: () => ({ Authorization: `Bearer ${token}` }),
+});
+
+const directToken = await client.getDirectAccessToken();
+// Returns: { token: 'xxx', headers: {...}, expiresAt: 123456 }
+```
+
+#### GitLabModelDiscovery
+
+Discovers available workflow models via GraphQL.
+
+```typescript
+const discovery = new GitLabModelDiscovery({
+  instanceUrl: 'https://gitlab.com',
+  getHeaders: () => ({ Authorization: `Bearer ${token}` }),
+});
+
+const models = await discovery.discover('gid://gitlab/Group/12345');
+// Returns: { defaultModel, selectableModels, pinnedModel, modelSwitchingEnabled }
+
+const effectiveRef = await discovery.getEffectiveModelRef(
+  'gid://gitlab/Group/12345',
+  'claude_sonnet_4_6'
+);
+```
+
+#### GitLabModelCache
+
+Persists model discovery results and user selections.
+
+```typescript
+const cache = new GitLabModelCache('/workspace/path', 'https://gitlab.com');
+
+cache.saveDiscovery(discoveredModels);
+cache.saveSelection('claude_sonnet_4_6', 'Claude Sonnet 4.6');
+
+const selectedRef = cache.getSelectedModelRef();
+const discovery = cache.getDiscovery();
+```
+
+#### GitLabWorkflowClient
+
+Low-level WebSocket client for DWS communication.
+
+```typescript
+const client = new GitLabWorkflowClient();
+
+await client.connect(
+  {
+    instanceUrl: 'https://gitlab.com',
+    modelRef: 'claude_sonnet_4_6',
+    headers: { Authorization: `Bearer ${token}` },
+    projectId: 'my-group/my-project',
+  },
+  (event) => {
+    if (event.type === 'checkpoint') {
+      console.log('Checkpoint:', event.data);
+    } else if (event.type === 'tool-request') {
+      console.log('Tool request:', event.data);
+    }
+  }
+);
+
+client.sendStartRequest({ workflowID: '123', goal: 'Refactor code', ... });
+client.sendActionResponse('request-id', 'tool result');
+client.stop();
+```
+
+#### GitLabWorkflowTokenClient
+
+Manages DWS token lifecycle and workflow creation.
+
+```typescript
+const tokenClient = new GitLabWorkflowTokenClient({
+  instanceUrl: 'https://gitlab.com',
+  getHeaders: () => ({ Authorization: `Bearer ${token}` }),
+});
+
+const token = await tokenClient.getToken('chat', 'gid://gitlab/Group/12345');
+const workflowId = await tokenClient.createWorkflow('Refactor authentication', {
+  projectId: 'my-group/my-project',
+});
+```
+
+## 📚 API Reference
+
+### Provider Configuration
+
+```typescript
+interface GitLabProviderSettings {
+  instanceUrl?: string; // Default: 'https://gitlab.com'
+  apiKey?: string; // PAT or OAuth access token
+  refreshToken?: string; // OAuth refresh token
+  name?: string; // Provider name prefix
+  headers?: Record<string, string>; // Custom headers for GitLab API
+  aiGatewayHeaders?: Record<string, string>; // Custom headers for AI Gateway proxy
+  fetch?: typeof fetch; // Custom fetch implementation
+  aiGatewayUrl?: string; // AI Gateway URL (default: 'https://cloud.gitlab.com')
+}
+```
+
+### Environment Variables
+
+| Variable                | Description                                 | Default                    |
+| ----------------------- | ------------------------------------------- | -------------------------- |
+| `GITLAB_TOKEN`          | GitLab Personal Access Token or OAuth token | -                          |
+| `GITLAB_INSTANCE_URL`   | GitLab instance URL                         | `https://gitlab.com`       |
+| `GITLAB_AI_GATEWAY_URL` | AI Gateway URL for Anthropic proxy          | `https://cloud.gitlab.com` |
+
+### Agentic Chat Options
+
+```typescript
+interface GitLabAgenticOptions {
+  providerModel?: string; // Override the backend model (e.g., 'claude-sonnet-4-5-20250929' or 'gpt-5.1-2025-11-13')
+  maxTokens?: number; // Default: 8192
+  featureFlags?: Record<string, boolean>; // GitLab feature flags
+  aiGatewayHeaders?: Record<string, string>; // Custom headers for AI Gateway proxy (per-model)
+}
+```
+
+**Note:** The `providerModel` option allows you to override the automatically mapped model. The provider will validate that the override is compatible with the model ID's provider (e.g., you cannot use an OpenAI model with a `duo-chat-opus-*` model ID).
+
+### Error Handling
+
+```typescript
+import { GitLabError } from 'gitlab-ai-provider';
+
+try {
+  const result = await generateText({ model, prompt });
+} catch (error) {
+  if (error instanceof GitLabError) {
+    if (error.isAuthError()) {
+      console.error('Authentication failed');
+    } else if (error.isRateLimitError()) {
+      console.error('Rate limit exceeded');
+    } else if (error.isServerError()) {
+      console.error('Server error:', error.statusCode);
+    }
+  }
+}
+```
+
+## 🔧 Development
+
+### Build
+
+```bash
+npm run build          # Build once
+npm run build:watch    # Build in watch mode
+```
+
+### Testing
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Run tests in watch mode
+```
+
+### Code Quality
+
+```bash
+npm run lint          # Lint code
+npm run lint:fix      # Lint and auto-fix
+npm run format        # Format code
+npm run format:check  # Check formatting
+npm run type-check    # TypeScript type checking
+```
+
+### Project Structure
+
+```
+gitlab-ai-provider/
+├── src/
+│   ├── index.ts                            # Main exports
+│   ├── gitlab-provider.ts                  # Provider factory
+│   ├── gitlab-anthropic-language-model.ts  # Anthropic/Claude model
+│   ├── gitlab-openai-language-model.ts     # OpenAI/GPT model
+│   ├── gitlab-workflow-language-model.ts   # Workflow/DWS model
+│   ├── gitlab-workflow-client.ts           # WebSocket client for DWS
+│   ├── gitlab-workflow-token-client.ts     # DWS token management
+│   ├── gitlab-workflow-builtins.ts         # Built-in tool mapping
+│   ├── gitlab-workflow-types.ts            # DWS protocol types
+│   ├── gitlab-model-discovery.ts           # GraphQL model discovery
+│   ├── gitlab-model-cache.ts               # Model selection cache
+│   ├── model-mappings.ts                   # Model ID mappings
+│   ├── gitlab-direct-access.ts             # Direct access tokens
+│   ├── gitlab-oauth-manager.ts             # OAuth management
+│   ├── gitlab-oauth-types.ts               # OAuth types
+│   ├── gitlab-project-detector.ts          # Project detection
+│   ├── gitlab-project-cache.ts             # Project caching
+│   ├── gitlab-api-types.ts                 # API types
+│   └── gitlab-error.ts                     # Error handling
+├── tests/                                  # Test files (300 tests)
+├── dist/                                   # Build output
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+└── vitest.config.ts
+```
+
+## 📝 Code Style
+
+- **Imports**: Named imports, organized by external → internal → types
+- **Formatting**: Single quotes, semicolons, 100 char line width, 2 space indent
+- **Types**: Interfaces for public APIs, Zod schemas for runtime validation
+- **Naming**: camelCase (variables/functions), PascalCase (classes/types), kebab-case (files)
+- **Exports**: Named exports only (no default exports)
+- **Comments**: JSDoc for public APIs with @param/@returns
+
+---
+
+## Assistant
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](https://gitlab.com/vglafirov/gitlab-ai-provider/-/blob/main/CONTRIBUTING.md) for detailed guidelines on:
+
+- Code style and conventions
+- Development workflow
+- Testing requirements
+- Submitting merge requests
+- Developer Certificate of Origin and License
+
+**Quick Start for Contributors**:
+
+1. **Commit Messages**: Use conventional commits format
+
+```
+
+feat(scope): add new feature
+fix(scope): fix bug
+docs(scope): update documentation
+
+```
+
+2. **Code Quality**: Ensure all checks pass
+
+```bash
+npm run lint
+npm run type-check
+npm test
+```
+
+3. **Testing**: Add tests for new features
+
+## 🔗 Links
+
+- [GitLab Repository](https://gitlab.com/vglafirov/gitlab-ai-provider)
+- [npm Package](https://www.npmjs.com/package/gitlab-ai-provider)
+- [Issue Tracker](https://gitlab.com/vglafirov/gitlab-ai-provider/-/issues)
+- [Contributing Guide](https://gitlab.com/vglafirov/gitlab-ai-provider/-/blob/main/CONTRIBUTING.md)
+- [Changelog](https://gitlab.com/vglafirov/gitlab-ai-provider/-/blob/main/CHANGELOG.md)
+- [Agent Guidelines](https://gitlab.com/vglafirov/gitlab-ai-provider/-/blob/main/AGENTS.md)
+
+## 🙏 Acknowledgments
+
+This project is built on top of:
+
+- [Vercel AI SDK](https://sdk.vercel.ai/)
+- [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-typescript)
+- [OpenAI SDK](https://github.com/openai/openai-node)
+- [GitLab Duo](https://about.gitlab.com/gitlab-duo/)
+
+---
+
+**Made with ❤️ for the OpenCode community**
+
+---