jwadow commited on
Commit ·
d709b23
1
Parent(s): b0850b9
docs: update architecture documentation to match codebase
Browse files- docs/en/ARCHITECTURE.md +227 -18
- 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 |
-
│
|
|
|
|
|
|
|
| 36 |
│
|
| 37 |
├── tests/ # Tests
|
|
|
|
| 38 |
│ ├── unit/ # Unit tests
|
| 39 |
│ └── integration/ # Integration tests
|
| 40 |
│
|
| 41 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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.
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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.
|
| 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 |
-
###
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 (
|
| 154 |
-
| `5xx` | Exponential backoff (up to
|
| 155 |
| Timeout | Exponential backoff |
|
| 156 |
|
| 157 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
-
|
| 305 |
- `request_body.json` — incoming request
|
| 306 |
-
- `
|
| 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 |
-
│
|
|
|
|
|
|
|
| 36 |
│
|
| 37 |
├── tests/ # Тесты
|
|
|
|
| 38 |
│ ├── unit/ # Юнит-тесты
|
| 39 |
│ └── integration/ # Интеграционные тесты
|
| 40 |
│
|
| 41 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 42 |
```
|
| 43 |
|
| 44 |
## 3. Архитектурная Топология и Компоненты
|
| 45 |
|
| 46 |
Система построена на базе асинхронного фреймворка `FastAPI` и использует событийную модель управления жизненным циклом (`Lifespan Events`).
|
| 47 |
|
| 48 |
-
### 3.1.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
-
###
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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.
|
| 123 |
|
| 124 |
#### AwsEventStreamParser
|
| 125 |
|
|
@@ -141,7 +257,32 @@ OpenAI messages преобразуются в Kiro conversationState:
|
|
| 141 |
| `usage` | Информация о потреблении кредитов |
|
| 142 |
| `context_usage` | Процент использования контекста |
|
| 143 |
|
| 144 |
-
###
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 145 |
|
| 146 |
#### KiroHttpClient
|
| 147 |
|
|
@@ -149,12 +290,59 @@ OpenAI messages преобразуются в Kiro conversationState:
|
|
| 149 |
|
| 150 |
| Код ошибки | Действие |
|
| 151 |
|------------|----------|
|
| 152 |
-
| `403` | Refresh токена + повтор |
|
| 153 |
-
| `429` | Exponential backoff (
|
| 154 |
-
| `5xx` | Exponential backoff (до
|
| 155 |
| Timeout | Exponential backoff |
|
| 156 |
|
| 157 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
-
|
| 305 |
- `request_body.json` — входящий запрос
|
| 306 |
-
- `
|
| 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` | Продвинутое логирование |
|