jwadow commited on
Commit
d709b23
·
1 Parent(s): b0850b9

docs: update architecture documentation to match codebase

Browse files
Files changed (2) hide show
  1. docs/en/ARCHITECTURE.md +227 -18
  2. docs/ru/ARCHITECTURE.md +227 -18
docs/en/ARCHITECTURE.md CHANGED
@@ -17,12 +17,11 @@ The project is organized as a modular Python package `kiro_gateway/`:
17
  ```
18
  kiro-openai-gateway/
19
  ├── main.py # Entry point, FastAPI application creation
20
- ├── config.py # Legacy config (for backward compatibility)
21
- ├── debug_logger.py # Debug logging of requests
22
  ├── requirements.txt # Python dependencies
 
23
  │
24
  ├── kiro_gateway/ # Main package
25
- │ ├── __init__.py # Package exports
26
  │ ├── config.py # Configuration and constants
27
  │ ├── models.py # Pydantic models for OpenAI API
28
  │ ├── auth.py # KiroAuthManager - token management
@@ -32,20 +31,41 @@ kiro-openai-gateway/
32
  │ ├── parsers.py # AWS SSE stream parsers
33
  │ ├── streaming.py # Response streaming logic
34
  │ ├── http_client.py # HTTP client with retry logic
35
- │ └── routes.py # FastAPI routes
 
 
36
  │
37
  ├── tests/ # Tests
 
38
  │ ├── unit/ # Unit tests
39
  │ └── integration/ # Integration tests
40
  │
41
- └── debug_logs/ # Debug logs (generated)
 
 
 
 
42
  ```
43
 
44
  ## 3. Architectural Topology and Components
45
 
46
  The system is built on the asynchronous `FastAPI` framework and uses an event-driven lifecycle management model (`Lifespan Events`).
47
 
48
- ### 3.1. Configuration Module (`kiro_gateway/config.py`)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
49
 
50
  Centralized storage of all settings:
51
 
@@ -53,12 +73,55 @@ Centralized storage of all settings:
53
  |-----------|-------------|---------------|
54
  | `PROXY_API_KEY` | API key for proxy access | `changeme_proxy_secret` |
55
  | `REFRESH_TOKEN` | Kiro refresh token | from `.env` |
 
56
  | `REGION` | AWS region | `us-east-1` |
 
57
  | `TOKEN_REFRESH_THRESHOLD` | Time before token refresh | 600 sec (10 min) |
58
  | `MAX_RETRIES` | Max retry attempts | 3 |
 
59
  | `MODEL_CACHE_TTL` | Model cache TTL | 3600 sec (1 hour) |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
60
 
61
- ### 3.2. State Management Layer
62
 
63
  #### KiroAuthManager (`kiro_gateway/auth.py`)
64
 
@@ -74,11 +137,24 @@ Centralized storage of all settings:
74
 
75
  **Concurrency Control:** Uses `asyncio.Lock` to protect against race conditions.
76
 
 
 
 
 
 
 
 
 
 
 
 
 
77
  ```python
78
  # Usage example
79
  auth_manager = KiroAuthManager(
80
  refresh_token="your_token",
81
- region="us-east-1"
 
82
  )
83
  token = await auth_manager.get_access_token()
84
  ```
@@ -92,7 +168,24 @@ token = await auth_manager.get_access_token()
92
  - Cache TTL: 1 hour
93
  - Fallback to static model list
94
 
95
- ### 3.3. Conversion Layer (`kiro_gateway/converters.py`)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
96
 
97
  #### Message Conversion
98
 
@@ -104,6 +197,27 @@ OpenAI messages are transformed into Kiro conversationState:
104
  4. **Tool calls** — OpenAI tools format support
105
  5. **Tool results** — correct transmission of tool call results
106
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
107
  #### Model Mapping
108
 
109
  External model names are converted to internal Kiro IDs:
@@ -113,13 +227,15 @@ External model names are converted to internal Kiro IDs:
113
  | `claude-opus-4-5` | `claude-opus-4.5` |
114
  | `claude-opus-4-5-20251101` | `claude-opus-4.5` |
115
  | `claude-haiku-4-5` | `claude-haiku-4.5` |
 
116
  | `claude-sonnet-4-5` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
117
  | `claude-sonnet-4-5-20250929` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
118
  | `claude-sonnet-4` | `CLAUDE_SONNET_4_20250514_V1_0` |
119
  | `claude-sonnet-4-20250514` | `CLAUDE_SONNET_4_20250514_V1_0` |
120
  | `claude-3-7-sonnet-20250219` | `CLAUDE_3_7_SONNET_20250219_V1_0` |
 
121
 
122
- ### 3.4. Parsing Layer (`kiro_gateway/parsers.py`)
123
 
124
  #### AwsEventStreamParser
125
 
@@ -141,7 +257,32 @@ Advanced AWS SSE format parser with support for:
141
  | `usage` | Credit consumption information |
142
  | `context_usage` | Context usage percentage |
143
 
144
- ### 3.5. HTTP Client (`kiro_gateway/http_client.py`)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
145
 
146
  #### KiroHttpClient
147
 
@@ -149,12 +290,59 @@ Automatic error handling with exponential backoff:
149
 
150
  | Error Code | Action |
151
  |------------|--------|
152
- | `403` | Token refresh + retry |
153
- | `429` | Exponential backoff (1s, 2s, 4s) |
154
- | `5xx` | Exponential backoff (up to 3 attempts) |
155
  | Timeout | Exponential backoff |
156
 
157
- ### 3.6. Kiro API Endpoints
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
158
 
159
  All URLs are dynamically formed based on the region:
160
 
@@ -242,6 +430,13 @@ PROXY_API_KEY="your_proxy_secret"
242
  PROFILE_ARN="arn:aws:codewhisperer:..."
243
  KIRO_REGION="us-east-1"
244
  KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"
 
 
 
 
 
 
 
245
  ```
246
 
247
  ### JSON Credentials File (optional)
@@ -301,9 +496,9 @@ data: [DONE]
301
 
302
  ### Debugging
303
 
304
- All requests and responses are logged in `debug_logs/`:
305
  - `request_body.json` — incoming request
306
- - `google_request_body.json` — request to Kiro API
307
  - `response_stream_raw.txt` — raw stream from Kiro
308
  - `response_stream_modified.txt` — transformed stream
309
 
@@ -335,4 +530,18 @@ class GeminiConverter:
335
 
336
  class GeminiParser:
337
  """Gemini SSE stream parsing."""
338
- pass
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17
  ```
18
  kiro-openai-gateway/
19
  ├── main.py # Entry point, FastAPI application creation
 
 
20
  ├── requirements.txt # Python dependencies
21
+ ├── .env.example # Environment configuration example
22
  │
23
  ├── kiro_gateway/ # Main package
24
+ │ ├── __init__.py # Package exports, version
25
  │ ├── config.py # Configuration and constants
26
  │ ├── models.py # Pydantic models for OpenAI API
27
  │ ├── auth.py # KiroAuthManager - token management
 
31
  │ ├── parsers.py # AWS SSE stream parsers
32
  │ ├── streaming.py # Response streaming logic
33
  │ ├── http_client.py # HTTP client with retry logic
34
+ │ ├── routes.py # FastAPI routes
35
+ │ ├── debug_logger.py # Debug request logging
36
+ │ └── exceptions.py # Exception handlers
37
  │
38
  ├── tests/ # Tests
39
+ │ ├── conftest.py # Pytest fixtures
40
  │ ├── unit/ # Unit tests
41
  │ └── integration/ # Integration tests
42
  │
43
+ ├── docs/ # Documentation
44
+ │ ├── ru/ # Russian version
45
+ │ └── en/ # English version
46
+ │
47
+ └── debug_logs/ # Debug logs (generated when DEBUG_LAST_REQUEST=true)
48
  ```
49
 
50
  ## 3. Architectural Topology and Components
51
 
52
  The system is built on the asynchronous `FastAPI` framework and uses an event-driven lifecycle management model (`Lifespan Events`).
53
 
54
+ ### 3.1. Entry Point (`main.py`)
55
+
56
+ The `main.py` file is responsible for:
57
+
58
+ 1. **Logging configuration** — Loguru setup with colored output
59
+ 2. **Configuration validation** — `validate_configuration()` function checks:
60
+ - Presence of `.env` file
61
+ - Presence of credentials (REFRESH_TOKEN or KIRO_CREDS_FILE)
62
+ 3. **Lifespan Manager** — creation and initialization of:
63
+ - `KiroAuthManager` for token management
64
+ - `ModelInfoCache` for model caching
65
+ 4. **Error handler registration** — `validation_exception_handler` for 422 errors
66
+ 5. **Route connection** — `app.include_router(router)`
67
+
68
+ ### 3.2. Configuration Module (`kiro_gateway/config.py`)
69
 
70
  Centralized storage of all settings:
71
 
 
73
  |-----------|-------------|---------------|
74
  | `PROXY_API_KEY` | API key for proxy access | `changeme_proxy_secret` |
75
  | `REFRESH_TOKEN` | Kiro refresh token | from `.env` |
76
+ | `PROFILE_ARN` | AWS CodeWhisperer profile ARN | from `.env` |
77
  | `REGION` | AWS region | `us-east-1` |
78
+ | `KIRO_CREDS_FILE` | Path to JSON credentials file | from `.env` |
79
  | `TOKEN_REFRESH_THRESHOLD` | Time before token refresh | 600 sec (10 min) |
80
  | `MAX_RETRIES` | Max retry attempts | 3 |
81
+ | `BASE_RETRY_DELAY` | Base retry delay | 1.0 sec |
82
  | `MODEL_CACHE_TTL` | Model cache TTL | 3600 sec (1 hour) |
83
+ | `DEFAULT_MAX_INPUT_TOKENS` | Default max input tokens | 200000 |
84
+ | `TOOL_DESCRIPTION_MAX_LENGTH` | Max tool description length | 10000 characters |
85
+ | `DEBUG_LAST_REQUEST` | Enable debug logging | `false` |
86
+ | `DEBUG_DIR` | Debug logs directory | `debug_logs` |
87
+ | `APP_VERSION` | Application version | `1.0.1` |
88
+
89
+ **Helper functions:**
90
+ - `get_kiro_refresh_url(region)` — URL for token refresh
91
+ - `get_kiro_api_host(region)` — main API host
92
+ - `get_kiro_q_host(region)` — Q API host
93
+ - `get_internal_model_id(external_model)` — model name conversion
94
+
95
+ ### 3.3. Pydantic Models (`kiro_gateway/models.py`)
96
+
97
+ #### Models for `/v1/models`
98
+
99
+ | Model | Description |
100
+ |-------|-------------|
101
+ | `OpenAIModel` | AI model description (id, object, created, owned_by) |
102
+ | `ModelList` | Model list for endpoint response |
103
+
104
+ #### Models for `/v1/chat/completions`
105
+
106
+ | Model | Description |
107
+ |-------|-------------|
108
+ | `ChatMessage` | Chat message (role, content, tool_calls, tool_call_id) |
109
+ | `ToolFunction` | Tool function description (name, description, parameters) |
110
+ | `Tool` | OpenAI format tool (type, function) |
111
+ | `ChatCompletionRequest` | Generation request (model, messages, stream, tools, ...) |
112
+
113
+ #### Response Models
114
+
115
+ | Model | Description |
116
+ |-------|-------------|
117
+ | `ChatCompletionChoice` | Single response variant |
118
+ | `ChatCompletionUsage` | Token information (prompt_tokens, completion_tokens, credits_used) |
119
+ | `ChatCompletionResponse` | Full response (non-streaming) |
120
+ | `ChatCompletionChunk` | Streaming chunk |
121
+ | `ChatCompletionChunkDelta` | Delta changes in chunk |
122
+ | `ChatCompletionChunkChoice` | Variant in streaming chunk |
123
 
124
+ ### 3.4. State Management Layer
125
 
126
  #### KiroAuthManager (`kiro_gateway/auth.py`)
127
 
 
137
 
138
  **Concurrency Control:** Uses `asyncio.Lock` to protect against race conditions.
139
 
140
+ **Main methods:**
141
+ - `get_access_token()` — returns valid token, refreshing if necessary
142
+ - `force_refresh()` — forced token refresh (on 403)
143
+ - `is_token_expiring_soon()` — expiration time check
144
+
145
+ **Properties:**
146
+ - `profile_arn` — profile ARN
147
+ - `region` — AWS region
148
+ - `api_host` — API host for region
149
+ - `q_host` — Q API host for region
150
+ - `fingerprint` — unique machine fingerprint
151
+
152
  ```python
153
  # Usage example
154
  auth_manager = KiroAuthManager(
155
  refresh_token="your_token",
156
+ region="us-east-1",
157
+ creds_file="~/.aws/sso/cache/kiro-auth-token.json"
158
  )
159
  token = await auth_manager.get_access_token()
160
  ```
 
168
  - Cache TTL: 1 hour
169
  - Fallback to static model list
170
 
171
+ **Main methods:**
172
+ - `update(models_data)` — cache update
173
+ - `get(model_id)` — get model information
174
+ - `get_max_input_tokens(model_id)` — get token limit
175
+ - `is_empty()` / `is_stale()` — cache state check
176
+ - `get_all_model_ids()` — list of all model IDs
177
+
178
+ ### 3.5. Helper Utilities (`kiro_gateway/utils.py`)
179
+
180
+ | Function | Description |
181
+ |----------|-------------|
182
+ | `get_machine_fingerprint()` | SHA256 hash of `{hostname}-{username}-kiro-gateway` |
183
+ | `get_kiro_headers(auth_manager, token)` | Form headers for Kiro API |
184
+ | `generate_completion_id()` | ID in format `chatcmpl-{uuid_hex}` |
185
+ | `generate_conversation_id()` | UUID for conversation |
186
+ | `generate_tool_call_id()` | ID in format `call_{uuid_hex[:8]}` |
187
+
188
+ ### 3.6. Conversion Layer (`kiro_gateway/converters.py`)
189
 
190
  #### Message Conversion
191
 
 
197
  4. **Tool calls** — OpenAI tools format support
198
  5. **Tool results** — correct transmission of tool call results
199
 
200
+ #### Long Tool Description Handling
201
+
202
+ **Problem:** Kiro API returns error 400 for too long descriptions in `toolSpecification.description`.
203
+
204
+ **Solution:** Tool Documentation Reference Pattern
205
+ - If `description ≤ TOOL_DESCRIPTION_MAX_LENGTH` → leave as is
206
+ - If `description > TOOL_DESCRIPTION_MAX_LENGTH`:
207
+ * In `toolSpecification.description` → reference: `"[Full documentation in system prompt under '## Tool: {name}']"`
208
+ * In system prompt, section `"## Tool: {name}"` with full description is added
209
+
210
+ **Function:** `process_tools_with_long_descriptions(tools)` → `(processed_tools, tool_documentation)`
211
+
212
+ #### Main Functions
213
+
214
+ | Function | Description |
215
+ |----------|-------------|
216
+ | `extract_text_content(content)` | Extract text from various formats |
217
+ | `merge_adjacent_messages(messages)` | Merge adjacent messages with same role |
218
+ | `build_kiro_history(messages, model_id)` | Build history array for Kiro |
219
+ | `build_kiro_payload(request_data, conversation_id, profile_arn)` | Full payload for request |
220
+
221
  #### Model Mapping
222
 
223
  External model names are converted to internal Kiro IDs:
 
227
  | `claude-opus-4-5` | `claude-opus-4.5` |
228
  | `claude-opus-4-5-20251101` | `claude-opus-4.5` |
229
  | `claude-haiku-4-5` | `claude-haiku-4.5` |
230
+ | `claude-haiku-4.5` | `claude-haiku-4.5` (direct passthrough) |
231
  | `claude-sonnet-4-5` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
232
  | `claude-sonnet-4-5-20250929` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
233
  | `claude-sonnet-4` | `CLAUDE_SONNET_4_20250514_V1_0` |
234
  | `claude-sonnet-4-20250514` | `CLAUDE_SONNET_4_20250514_V1_0` |
235
  | `claude-3-7-sonnet-20250219` | `CLAUDE_3_7_SONNET_20250219_V1_0` |
236
+ | `auto` | `claude-sonnet-4.5` (alias) |
237
 
238
+ ### 3.7. Parsing Layer (`kiro_gateway/parsers.py`)
239
 
240
  #### AwsEventStreamParser
241
 
 
257
  | `usage` | Credit consumption information |
258
  | `context_usage` | Context usage percentage |
259
 
260
+ #### Helper Functions
261
+
262
+ | Function | Description |
263
+ |----------|-------------|
264
+ | `find_matching_brace(text, start_pos)` | Find closing brace with nesting support |
265
+ | `parse_bracket_tool_calls(response_text)` | Parse `[Called func with args: {...}]` |
266
+ | `deduplicate_tool_calls(tool_calls)` | Remove duplicate tool calls |
267
+
268
+ ### 3.8. Streaming (`kiro_gateway/streaming.py`)
269
+
270
+ #### stream_kiro_to_openai
271
+
272
+ Async generator for transforming Kiro stream to OpenAI format.
273
+
274
+ **Functionality:**
275
+ - Parse AWS SSE stream via `AwsEventStreamParser`
276
+ - Form OpenAI `chat.completion.chunk`
277
+ - Handle tool calls (structured and bracket-style)
278
+ - Calculate usage based on `contextUsagePercentage`
279
+ - Debug logging via `debug_logger`
280
+
281
+ #### collect_stream_response
282
+
283
+ Collects full response from streaming for non-streaming mode.
284
+
285
+ ### 3.9. HTTP Client (`kiro_gateway/http_client.py`)
286
 
287
  #### KiroHttpClient
288
 
 
290
 
291
  | Error Code | Action |
292
  |------------|--------|
293
+ | `403` | Token refresh via `force_refresh()` + retry |
294
+ | `429` | Exponential backoff: `BASE_RETRY_DELAY * (2 ** attempt)` |
295
+ | `5xx` | Exponential backoff (up to MAX_RETRIES attempts) |
296
  | Timeout | Exponential backoff |
297
 
298
+ **Delay formula:** `1s, 2s, 4s` (with `BASE_RETRY_DELAY=1.0`)
299
+
300
+ **Methods:**
301
+ - `request_with_retry(method, url, json_data, stream)` — request with retry
302
+ - `close()` — close client
303
+
304
+ Supports async context manager (`async with`).
305
+
306
+ ### 3.10. Routes (`kiro_gateway/routes.py`)
307
+
308
+ | Endpoint | Method | Description |
309
+ |----------|--------|-------------|
310
+ | `/` | GET | Health check (status, message, version) |
311
+ | `/health` | GET | Detailed health check (status, timestamp, version) |
312
+ | `/v1/models` | GET | List of available models (requires API key) |
313
+ | `/v1/chat/completions` | POST | Chat completions (requires API key) |
314
+
315
+ **Authentication:** Bearer token in `Authorization` header
316
+
317
+ ### 3.11. Exception Handling (`kiro_gateway/exceptions.py`)
318
+
319
+ | Function | Description |
320
+ |----------|-------------|
321
+ | `sanitize_validation_errors(errors)` | Convert bytes to strings for JSON serialization |
322
+ | `validation_exception_handler(request, exc)` | Pydantic validation error handler (422) |
323
+
324
+ ### 3.12. Debug Logging (`kiro_gateway/debug_logger.py`)
325
+
326
+ **Class:** `DebugLogger` (singleton)
327
+
328
+ **Activation:** `DEBUG_LAST_REQUEST=true` in `.env`
329
+
330
+ **Methods:**
331
+ | Method | Description |
332
+ |--------|-------------|
333
+ | `prepare_new_request()` | Clear directory for new request |
334
+ | `log_request_body(body)` | Save incoming request |
335
+ | `log_kiro_request_body(body)` | Save request to Kiro API |
336
+ | `log_raw_chunk(chunk)` | Append raw chunk from Kiro |
337
+ | `log_modified_chunk(chunk)` | Append transformed chunk |
338
+
339
+ **Files in `debug_logs/`:**
340
+ - `request_body.json` — incoming request (OpenAI format)
341
+ - `kiro_request_body.json` — request to Kiro API
342
+ - `response_stream_raw.txt` — raw stream from Kiro
343
+ - `response_stream_modified.txt` — transformed stream (OpenAI format)
344
+
345
+ ### 3.13. Kiro API Endpoints
346
 
347
  All URLs are dynamically formed based on the region:
348
 
 
430
  PROFILE_ARN="arn:aws:codewhisperer:..."
431
  KIRO_REGION="us-east-1"
432
  KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"
433
+
434
+ # Debug
435
+ DEBUG_LAST_REQUEST="false"
436
+ DEBUG_DIR="debug_logs"
437
+
438
+ # Limits
439
+ TOOL_DESCRIPTION_MAX_LENGTH="10000"
440
  ```
441
 
442
  ### JSON Credentials File (optional)
 
496
 
497
  ### Debugging
498
 
499
+ When `DEBUG_LAST_REQUEST=true`, all requests and responses are logged in `debug_logs/`:
500
  - `request_body.json` — incoming request
501
+ - `kiro_request_body.json` — request to Kiro API
502
  - `response_stream_raw.txt` — raw stream from Kiro
503
  - `response_stream_modified.txt` — transformed stream
504
 
 
530
 
531
  class GeminiParser:
532
  """Gemini SSE stream parsing."""
533
+ pass
534
+ ```
535
+
536
+ ## 10. Dependencies
537
+
538
+ Main project dependencies (from `requirements.txt`):
539
+
540
+ | Package | Purpose |
541
+ |---------|---------|
542
+ | `fastapi` | Asynchronous web framework |
543
+ | `uvicorn` | ASGI server |
544
+ | `httpx` | Asynchronous HTTP client |
545
+ | `pydantic` | Data validation and models |
546
+ | `python-dotenv` | Environment variable loading |
547
+ | `loguru` | Advanced logging |
docs/ru/ARCHITECTURE.md CHANGED
@@ -17,12 +17,11 @@
17
  ```
18
  kiro-openai-gateway/
19
  ├── main.py # Точка входа, создание FastAPI приложения
20
- ├── config.py # Legacy конфиг (для обратной совместимости)
21
- ├── debug_logger.py # Отладочное логирование запросов
22
  ├── requirements.txt # Зависимости Python
 
23
  │
24
  ├── kiro_gateway/ # Основной пакет
25
- │ ├── __init__.py # Экспорты пакета
26
  │ ├── config.py # Конфигурация и константы
27
  │ ├── models.py # Pydantic модели OpenAI API
28
  │ ├── auth.py # KiroAuthManager - управление токенами
@@ -32,20 +31,41 @@ kiro-openai-gateway/
32
  │ ├── parsers.py # Парсеры AWS SSE потоков
33
  │ ├── streaming.py # Логика стриминга ответов
34
  │ ├── http_client.py # HTTP клиент с retry логикой
35
- │ └── routes.py # FastAPI роуты
 
 
36
  │
37
  ├── tests/ # Тесты
 
38
  │ ├── unit/ # Юнит-тесты
39
  │ └── integration/ # Интеграционные тесты
40
  │
41
- └── debug_logs/ # Отладочные логи (генерируются)
 
 
 
 
42
  ```
43
 
44
  ## 3. Архитектурная Топология и Компоненты
45
 
46
  Система построена на базе асинхронного фреймворка `FastAPI` и использует событийную модель управления жизненным циклом (`Lifespan Events`).
47
 
48
- ### 3.1. Модуль конфигурации (`kiro_gateway/config.py`)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
49
 
50
  Централизованное хранение всех настроек:
51
 
@@ -53,12 +73,55 @@ kiro-openai-gateway/
53
  |----------|----------|----------------------|
54
  | `PROXY_API_KEY` | API ключ для доступа к прокси | `changeme_proxy_secret` |
55
  | `REFRESH_TOKEN` | Refresh token Kiro | из `.env` |
 
56
  | `REGION` | Регион AWS | `us-east-1` |
 
57
  | `TOKEN_REFRESH_THRESHOLD` | Время до обновления токена | 600 сек (10 мин) |
58
  | `MAX_RETRIES` | Макс. количество повторов | 3 |
 
59
  | `MODEL_CACHE_TTL` | TTL кэша моделей | 3600 сек (1 час) |
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
60
 
61
- ### 3.2. Управление Состоянием (State Management Layer)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
62
 
63
  #### KiroAuthManager (`kiro_gateway/auth.py`)
64
 
@@ -74,11 +137,24 @@ kiro-openai-gateway/
74
 
75
  **Concurrency Control:** Использует `asyncio.Lock` для защиты от состояния гонки.
76
 
 
 
 
 
 
 
 
 
 
 
 
 
77
  ```python
78
  # Пример использования
79
  auth_manager = KiroAuthManager(
80
  refresh_token="your_token",
81
- region="us-east-1"
 
82
  )
83
  token = await auth_manager.get_access_token()
84
  ```
@@ -92,7 +168,24 @@ token = await auth_manager.get_access_token()
92
  - TTL кэша: 1 час
93
  - Fallback на статический список моделей
94
 
95
- ### 3.3. Слой Конвертации (`kiro_gateway/converters.py`)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
96
 
97
  #### Конвертация сообщений
98
 
@@ -104,6 +197,27 @@ OpenAI messages преобразуются в Kiro conversationState:
104
  4. **Tool calls** — поддержка OpenAI tools формата
105
  5. **Tool results** — корректная передача результатов вызова инструментов
106
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
107
  #### Маппинг моделей
108
 
109
  Внешние имена моделей преобразуются во внутренние ID Kiro:
@@ -113,13 +227,15 @@ OpenAI messages преобразуются в Kiro conversationState:
113
  | `claude-opus-4-5` | `claude-opus-4.5` |
114
  | `claude-opus-4-5-20251101` | `claude-opus-4.5` |
115
  | `claude-haiku-4-5` | `claude-haiku-4.5` |
 
116
  | `claude-sonnet-4-5` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
117
  | `claude-sonnet-4-5-20250929` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
118
  | `claude-sonnet-4` | `CLAUDE_SONNET_4_20250514_V1_0` |
119
  | `claude-sonnet-4-20250514` | `CLAUDE_SONNET_4_20250514_V1_0` |
120
  | `claude-3-7-sonnet-20250219` | `CLAUDE_3_7_SONNET_20250219_V1_0` |
 
121
 
122
- ### 3.4. Слой Парсинга (`kiro_gateway/parsers.py`)
123
 
124
  #### AwsEventStreamParser
125
 
@@ -141,7 +257,32 @@ OpenAI messages преобразуются в Kiro conversationState:
141
  | `usage` | Информация о потреблении кредитов |
142
  | `context_usage` | Процент использования контекста |
143
 
144
- ### 3.5. HTTP Клиент (`kiro_gateway/http_client.py`)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
145
 
146
  #### KiroHttpClient
147
 
@@ -149,12 +290,59 @@ OpenAI messages преобразуются в Kiro conversationState:
149
 
150
  | Код ошибки | Действие |
151
  |------------|----------|
152
- | `403` | Refresh токена + повтор |
153
- | `429` | Exponential backoff (1s, 2s, 4s) |
154
- | `5xx` | Exponential backoff (до 3 попыток) |
155
  | Timeout | Exponential backoff |
156
 
157
- ### 3.6. Kiro API Endpoints
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
158
 
159
  Все URL динамически формируются на основе региона:
160
 
@@ -167,7 +355,7 @@ OpenAI messages преобразуются в Kiro conversationState:
167
  ```
168
  ┌─────────────────┐
169
  │ OpenAI Client │
170
- └────┬────────┘
171
  │ POST /v1/chat/completions
172
  ▼
173
  ┌─────────────────┐
@@ -242,6 +430,13 @@ PROXY_API_KEY="your_proxy_secret"
242
  PROFILE_ARN="arn:aws:codewhisperer:..."
243
  KIRO_REGION="us-east-1"
244
  KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"
 
 
 
 
 
 
 
245
  ```
246
 
247
  ### JSON файл credentials (опционально)
@@ -301,9 +496,9 @@ data: [DONE]
301
 
302
  ### Отладка
303
 
304
- Все запросы и ответы логируются в `debug_logs/`:
305
  - `request_body.json` — входящий запрос
306
- - `google_request_body.json` — запрос к Kiro API
307
  - `response_stream_raw.txt` — сырой поток от Kiro
308
  - `response_stream_modified.txt` — преобразованный поток
309
 
@@ -336,3 +531,17 @@ class GeminiConverter:
336
  class GeminiParser:
337
  """Парсинг SSE потока Gemini."""
338
  pass
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
17
  ```
18
  kiro-openai-gateway/
19
  ├── main.py # Точка входа, создание FastAPI приложения
 
 
20
  ├── requirements.txt # Зависимости Python
21
+ ├── .env.example # Пример конфигурации окружения
22
  │
23
  ├── kiro_gateway/ # Основной пакет
24
+ │ ├── __init__.py # Экспорты пакета, версия
25
  │ ├── config.py # Конфигурация и константы
26
  │ ├── models.py # Pydantic модели OpenAI API
27
  │ ├── auth.py # KiroAuthManager - управление токенами
 
31
  │ ├── parsers.py # Парсеры AWS SSE потоков
32
  │ ├── streaming.py # Логика стриминга ответов
33
  │ ├── http_client.py # HTTP клиент с retry логикой
34
+ │ ├── routes.py # FastAPI роуты
35
+ │ ├── debug_logger.py # Отладочное логирование запросов
36
+ │ └── exceptions.py # Обработчики исключений
37
  │
38
  ├── tests/ # Тесты
39
+ │ ├── conftest.py # Pytest fixtures
40
  │ ├── unit/ # Юнит-тесты
41
  │ └── integration/ # Интеграционные тесты
42
  │
43
+ ├── docs/ # Документация
44
+ │ ├── ru/ # Русская версия
45
+ │ └── en/ # Английская версия
46
+ │
47
+ └── debug_logs/ # Отладочные логи (генерируются при DEBUG_LAST_REQUEST=true)
48
  ```
49
 
50
  ## 3. Архитектурная Топология и Компоненты
51
 
52
  Система построена на базе асинхронного фреймворка `FastAPI` и использует событийную модель управления жизненным циклом (`Lifespan Events`).
53
 
54
+ ### 3.1. Точка входа (`main.py`)
55
+
56
+ Файл `main.py` отвечает за:
57
+
58
+ 1. **Конфигурацию логирования** — настройка Loguru с цветным выводом
59
+ 2. **Валидацию конфигурации** — функция `validate_configuration()` проверяет:
60
+ - Наличие файла `.env`
61
+ - Наличие credentials (REFRESH_TOKEN или KIRO_CREDS_FILE)
62
+ 3. **Lifespan Manager** — создание и инициализация:
63
+ - `KiroAuthManager` для управления токенами
64
+ - `ModelInfoCache` для кэширования моделей
65
+ 4. **Регистрация обработчиков ошибок** — `validation_exception_handler` для ошибок 422
66
+ 5. **Подключение роутов** — `app.include_router(router)`
67
+
68
+ ### 3.2. Модуль конфигурации (`kiro_gateway/config.py`)
69
 
70
  Централизованное хранение всех настроек:
71
 
 
73
  |----------|----------|----------------------|
74
  | `PROXY_API_KEY` | API ключ для доступа к прокси | `changeme_proxy_secret` |
75
  | `REFRESH_TOKEN` | Refresh token Kiro | из `.env` |
76
+ | `PROFILE_ARN` | ARN профиля AWS CodeWhisperer | из `.env` |
77
  | `REGION` | Регион AWS | `us-east-1` |
78
+ | `KIRO_CREDS_FILE` | Путь к JSON файлу credentials | из `.env` |
79
  | `TOKEN_REFRESH_THRESHOLD` | Время до обновления токена | 600 сек (10 мин) |
80
  | `MAX_RETRIES` | Макс. количество повторов | 3 |
81
+ | `BASE_RETRY_DELAY` | Базовая задержка retry | 1.0 сек |
82
  | `MODEL_CACHE_TTL` | TTL кэша моделей | 3600 сек (1 час) |
83
+ | `DEFAULT_MAX_INPUT_TOKENS` | Макс. input токенов по умолчанию | 200000 |
84
+ | `TOOL_DESCRIPTION_MAX_LENGTH` | Макс. длина описания tool | 10000 символов |
85
+ | `DEBUG_LAST_REQUEST` | Включить отладочное логирование | `false` |
86
+ | `DEBUG_DIR` | Директория для debug логов | `debug_logs` |
87
+ | `APP_VERSION` | Версия приложения | `1.0.1` |
88
+
89
+ **Вспомогательные функции:**
90
+ - `get_kiro_refresh_url(region)` — URL для обновления токена
91
+ - `get_kiro_api_host(region)` — хост основного API
92
+ - `get_kiro_q_host(region)` — хост Q API
93
+ - `get_internal_model_id(external_model)` — конвертация имени модели
94
+
95
+ ### 3.3. Pydantic Модели (`kiro_gateway/models.py`)
96
+
97
+ #### Модели для `/v1/models`
98
+
99
+ | Модель | Описание |
100
+ |--------|----------|
101
+ | `OpenAIModel` | Описание AI модели (id, object, created, owned_by) |
102
+ | `ModelList` | Список моделей для ответа endpoint |
103
 
104
+ #### Модели для `/v1/chat/completions`
105
+
106
+ | Модель | Описание |
107
+ |--------|----------|
108
+ | `ChatMessage` | Сообщение чата (role, content, tool_calls, tool_call_id) |
109
+ | `ToolFunction` | Описание функции инструмента (name, description, parameters) |
110
+ | `Tool` | Инструмент OpenAI формата (type, function) |
111
+ | `ChatCompletionRequest` | Запрос на генерацию (model, messages, stream, tools, ...) |
112
+
113
+ #### Модели ответов
114
+
115
+ | Модель | Описание |
116
+ |--------|----------|
117
+ | `ChatCompletionChoice` | Один вариант ответа |
118
+ | `ChatCompletionUsage` | Информация о токенах (prompt_tokens, completion_tokens, credits_used) |
119
+ | `ChatCompletionResponse` | Полный ответ (non-streaming) |
120
+ | `ChatCompletionChunk` | Streaming chunk |
121
+ | `ChatCompletionChunkDelta` | Дельта изменений в chunk |
122
+ | `ChatCompletionChunkChoice` | Вариант в streaming chunk |
123
+
124
+ ### 3.4. Управление Состоянием (State Management Layer)
125
 
126
  #### KiroAuthManager (`kiro_gateway/auth.py`)
127
 
 
137
 
138
  **Concurrency Control:** Использует `asyncio.Lock` для защиты от состояния гонки.
139
 
140
+ **Основные методы:**
141
+ - `get_access_token()` — возвращает действительный токен, обновляя при необходимости
142
+ - `force_refresh()` — принудительное обновление токена (при 403)
143
+ - `is_token_expiring_soon()` — проверка времени истечения
144
+
145
+ **Properties:**
146
+ - `profile_arn` — ARN профиля
147
+ - `region` — регион AWS
148
+ - `api_host` — хост API для региона
149
+ - `q_host` — хост Q API для региона
150
+ - `fingerprint` — уникальный fingerprint машины
151
+
152
  ```python
153
  # Пример использования
154
  auth_manager = KiroAuthManager(
155
  refresh_token="your_token",
156
+ region="us-east-1",
157
+ creds_file="~/.aws/sso/cache/kiro-auth-token.json"
158
  )
159
  token = await auth_manager.get_access_token()
160
  ```
 
168
  - TTL кэша: 1 час
169
  - Fallback на статический список моделей
170
 
171
+ **Основные методы:**
172
+ - `update(models_data)` — обновление кэша
173
+ - `get(model_id)` — получение информации о модели
174
+ - `get_max_input_tokens(model_id)` — получение лимита токенов
175
+ - `is_empty()` / `is_stale()` — проверка состояния кэша
176
+ - `get_all_model_ids()` — список всех ID моделей
177
+
178
+ ### 3.5. Вспомогательные Утилиты (`kiro_gateway/utils.py`)
179
+
180
+ | Функция | Описание |
181
+ |---------|----------|
182
+ | `get_machine_fingerprint()` | SHA256 хеш `{hostname}-{username}-kiro-gateway` |
183
+ | `get_kiro_headers(auth_manager, token)` | Формирование заголовков для Kiro API |
184
+ | `generate_completion_id()` | ID в формате `chatcmpl-{uuid_hex}` |
185
+ | `generate_conversation_id()` | UUID для разговора |
186
+ | `generate_tool_call_id()` | ID в формате `call_{uuid_hex[:8]}` |
187
+
188
+ ### 3.6. Слой Конвертации (`kiro_gateway/converters.py`)
189
 
190
  #### Конвертация сообщений
191
 
 
197
  4. **Tool calls** — поддержка OpenAI tools формата
198
  5. **Tool results** — корректная передача результатов вызова инструментов
199
 
200
+ #### Обработка длинных описаний Tools
201
+
202
+ **Проблема:** Kiro API возвращает ошибку 400 при слишком длинных описаниях в `toolSpecification.description`.
203
+
204
+ **Решение:** Tool Documentation Reference Pattern
205
+ - Если `description ≤ TOOL_DESCRIPTION_MAX_LENGTH` → оставляем как есть
206
+ - Если `description > TOOL_DESCRIPTION_MAX_LENGTH`:
207
+ * В `toolSpecification.description` → ссылка: `"[Full documentation in system prompt under '## Tool: {name}']"`
208
+ * В system prompt добавляется секция `"## Tool: {name}"` с ��олным описанием
209
+
210
+ **Функция:** `process_tools_with_long_descriptions(tools)` → `(processed_tools, tool_documentation)`
211
+
212
+ #### Основные функции
213
+
214
+ | Функция | Описание |
215
+ |---------|----------|
216
+ | `extract_text_content(content)` | Извлечение текста из различных форматов |
217
+ | `merge_adjacent_messages(messages)` | Объединение соседних сообщений с одной ролью |
218
+ | `build_kiro_history(messages, model_id)` | Построение массива history для Kiro |
219
+ | `build_kiro_payload(request_data, conversation_id, profile_arn)` | Полный payload для запроса |
220
+
221
  #### Маппинг моделей
222
 
223
  Внешние имена моделей преобразуются во внутренние ID Kiro:
 
227
  | `claude-opus-4-5` | `claude-opus-4.5` |
228
  | `claude-opus-4-5-20251101` | `claude-opus-4.5` |
229
  | `claude-haiku-4-5` | `claude-haiku-4.5` |
230
+ | `claude-haiku-4.5` | `claude-haiku-4.5` (прямой проброс) |
231
  | `claude-sonnet-4-5` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
232
  | `claude-sonnet-4-5-20250929` | `CLAUDE_SONNET_4_5_20250929_V1_0` |
233
  | `claude-sonnet-4` | `CLAUDE_SONNET_4_20250514_V1_0` |
234
  | `claude-sonnet-4-20250514` | `CLAUDE_SONNET_4_20250514_V1_0` |
235
  | `claude-3-7-sonnet-20250219` | `CLAUDE_3_7_SONNET_20250219_V1_0` |
236
+ | `auto` | `claude-sonnet-4.5` (алиас) |
237
 
238
+ ### 3.7. Слой Парсинга (`kiro_gateway/parsers.py`)
239
 
240
  #### AwsEventStreamParser
241
 
 
257
  | `usage` | Информация о потреблении кредитов |
258
  | `context_usage` | Процент использования контекста |
259
 
260
+ #### Вспомогательные функции
261
+
262
+ | Функция | Описание |
263
+ |---------|----------|
264
+ | `find_matching_brace(text, start_pos)` | Поиск закрывающей скобки с учётом вложенности |
265
+ | `parse_bracket_tool_calls(response_text)` | Парсинг `[Called func with args: {...}]` |
266
+ | `deduplicate_tool_calls(tool_calls)` | Удаление дубликатов tool calls |
267
+
268
+ ### 3.8. Streaming (`kiro_gateway/streaming.py`)
269
+
270
+ #### stream_kiro_to_openai
271
+
272
+ Асинхронный генератор для преобразования потока Kiro в OpenAI формат.
273
+
274
+ **Функциональность:**
275
+ - Парсинг AWS SSE stream через `AwsEventStreamParser`
276
+ - Формирование OpenAI `chat.completion.chunk`
277
+ - Обработка tool calls (структурированных и bracket-style)
278
+ - Вычисление usage на основе `contextUsagePercentage`
279
+ - Отладочное логирование через `debug_logger`
280
+
281
+ #### collect_stream_response
282
+
283
+ Собирает полный ответ из streaming потока для non-streaming режима.
284
+
285
+ ### 3.9. HTTP Клиент (`kiro_gateway/http_client.py`)
286
 
287
  #### KiroHttpClient
288
 
 
290
 
291
  | Код ошибки | Действие |
292
  |------------|----------|
293
+ | `403` | Refresh токена через `force_refresh()` + повтор |
294
+ | `429` | Exponential backoff: `BASE_RETRY_DELAY * (2 ** attempt)` |
295
+ | `5xx` | Exponential backoff (до MAX_RETRIES попыток) |
296
  | Timeout | Exponential backoff |
297
 
298
+ **Формула задержки:** `1s, 2s, 4s` (при `BASE_RETRY_DELAY=1.0`)
299
+
300
+ **Методы:**
301
+ - `request_with_retry(method, url, json_data, stream)` — запрос с retry
302
+ - `close()` — закрытие клиента
303
+
304
+ Поддерживает async context manager (`async with`).
305
+
306
+ ### 3.10. Роуты (`kiro_gateway/routes.py`)
307
+
308
+ | Endpoint | Метод | Описание |
309
+ |----------|-------|----------|
310
+ | `/` | GET | Health check (status, message, version) |
311
+ | `/health` | GET | Детальный health check (status, timestamp, version) |
312
+ | `/v1/models` | GET | Список доступных моделей (требует API key) |
313
+ | `/v1/chat/completions` | POST | Chat completions (требует API key) |
314
+
315
+ **Аутентификация:** Bearer token в заголовке `Authorization`
316
+
317
+ ### 3.11. Обработка Исключений (`kiro_gateway/exceptions.py`)
318
+
319
+ | Функция | Описание |
320
+ |---------|----------|
321
+ | `sanitize_validation_errors(errors)` | Конвертация bytes в строки для JSON-сериализации |
322
+ | `validation_exception_handler(request, exc)` | Обработчик ошибок валидации Pydantic (422) |
323
+
324
+ ### 3.12. Отладочное Логирование (`kiro_gateway/debug_logger.py`)
325
+
326
+ **Класс:** `DebugLogger` (синглтон)
327
+
328
+ **Активация:** `DEBUG_LAST_REQUEST=true` в `.env`
329
+
330
+ **Методы:**
331
+ | Метод | Описание |
332
+ |-------|----------|
333
+ | `prepare_new_request()` | Очистка директории для нового запроса |
334
+ | `log_request_body(body)` | Сохранение входящего запроса |
335
+ | `log_kiro_request_body(body)` | Сохранение запроса к Kiro API |
336
+ | `log_raw_chunk(chunk)` | Дописывание сырого chunk от Kiro |
337
+ | `log_modified_chunk(chunk)` | Дописывание преобразованного chunk |
338
+
339
+ **Файлы в `debug_logs/`:**
340
+ - `request_body.json` — входящий запрос (OpenAI формат)
341
+ - `kiro_request_body.json` — запрос к Kiro API
342
+ - `response_stream_raw.txt` — сырой поток от Kiro
343
+ - `response_stream_modified.txt` — преобразованный поток (OpenAI формат)
344
+
345
+ ### 3.13. Kiro API Endpoints
346
 
347
  Все URL динамически формируются на основе региона:
348
 
 
355
  ```
356
  ┌─────────────────┐
357
  │ OpenAI Client │
358
+ └────────┬────────┘
359
  │ POST /v1/chat/completions
360
  ▼
361
  ┌─────────────────┐
 
430
  PROFILE_ARN="arn:aws:codewhisperer:..."
431
  KIRO_REGION="us-east-1"
432
  KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"
433
+
434
+ # Отладка
435
+ DEBUG_LAST_REQUEST="false"
436
+ DEBUG_DIR="debug_logs"
437
+
438
+ # Лимиты
439
+ TOOL_DESCRIPTION_MAX_LENGTH="10000"
440
  ```
441
 
442
  ### JSON файл credentials (опционально)
 
496
 
497
  ### Отладка
498
 
499
+ При `DEBUG_LAST_REQUEST=true` все запросы и ответы логируются в `debug_logs/`:
500
  - `request_body.json` — входящий запрос
501
+ - `kiro_request_body.json` — запрос к Kiro API
502
  - `response_stream_raw.txt` — сырой поток от Kiro
503
  - `response_stream_modified.txt` — преобразованный поток
504
 
 
531
  class GeminiParser:
532
  """Парсинг SSE потока Gemini."""
533
  pass
534
+ ```
535
+
536
+ ## 10. Зависимости
537
+
538
+ Основные зависимости проекта (из `requirements.txt`):
539
+
540
+ | Пакет | Назначение |
541
+ |-------|------------|
542
+ | `fastapi` | Асинхронный веб-фреймворк |
543
+ | `uvicorn` | ASGI сервер |
544
+ | `httpx` | Асинхронный HTTP клиент |
545
+ | `pydantic` | Валидация данных и модели |
546
+ | `python-dotenv` | Загрузка переменных окружения |
547
+ | `loguru` | Продвинутое логирование |