From c6c260314be5fd98ca0baaac09e5c2bd1f707144 Mon Sep 17 00:00:00 2001 From: forge-bot Date: Tue, 14 Jul 2026 04:47:40 +0000 Subject: [PATCH] =?UTF-8?q?=EC=97=90=EC=9D=B4=EC=A0=84=ED=8A=B8=20?= =?UTF-8?q?=EB=9F=B0=ED=83=80=EC=9E=84=20=EB=B6=84=EC=84=9D=20=EC=82=B0?= =?UTF-8?q?=EC=B6=9C=EB=AC=BC=20=EC=83=9D=EC=84=B1=20(runtime-analysis-001?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- runtime-analysis/SPECIFICATION.md | 212 ++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 runtime-analysis/SPECIFICATION.md diff --git a/runtime-analysis/SPECIFICATION.md b/runtime-analysis/SPECIFICATION.md new file mode 100644 index 0000000..97d649b --- /dev/null +++ b/runtime-analysis/SPECIFICATION.md @@ -0,0 +1,212 @@ +# Agent Runtime Specification + +## 1. MiniMax Connection Specification + +### 1.1 Connection Pool + +| Property | Specification | +|----------|---------------| +| Pool Size | Configurable, default 100 | +| Connection Timeout | 30 seconds | +| Keep-Alive | Enabled by default | +| Idle Timeout | 60 seconds | +| Max Routes Per Route | 50 | + +### 1.2 Request Format + +```json +{ + "model": "string (required)", + "messages": [ + { + "role": "string (required)", + "content": "string (required)" + } + ], + "temperature": "number (0-2, optional)", + "max_tokens": "integer (optional)", + "stream": "boolean (optional, default false)" +} +``` + +### 1.3 Response Format + +```json +{ + "id": "string", + "model": "string", + "choices": [ + { + "index": "integer", + "message": { + "role": "string", + "content": "string" + }, + "finish_reason": "string" + } + ], + "usage": { + "prompt_tokens": "integer", + "completion_tokens": "integer", + "total_tokens": "integer" + } +} +``` + +--- + +## 2. Output Contract Specification + +### 2.1 Contract Version 1.0 + +| Field | Type | Required | Constraints | +|-------|------|----------|-------------| +| `content` | string | Yes | 0 ≤ length ≤ 128000 | +| `model` | string | Yes | Non-empty | +| `usage` | object | Yes | Contains prompt_tokens, completion_tokens, total_tokens | +| `finish_reason` | enum | Yes | One of: stop, length, content_filter, tool_calls | +| `tool_calls` | array | No | Array of tool call objects | +| `citations` | array | No | Array of citation objects | +| `metadata` | object | No | Arbitrary key-value pairs | + +### 2.2 Validation Rules + +1. **Schema Validation**: All required fields must be present +2. **Type Validation**: Field types must match specification +3. **Range Validation**: Numeric values within bounds +4. **Enum Validation**: Enumerated values from allowed set + +### 2.3 Validation Error Response + +```json +{ + "error": { + "code": "CONTRACT_VIOLATION", + "message": "string", + "violations": [ + { + "field": "string", + "expected": "string", + "actual": "string" + } + ] + } +} +``` + +--- + +## 3. Retry Mechanism Specification + +### 3.1 Retry Policy + +| Condition | Action | +|-----------|--------| +| Network timeout | Retry | +| HTTP 408 | Retry | +| HTTP 429 | Retry with longer backoff | +| HTTP 5xx | Retry | +| HTTP 400 | Do not retry | +| HTTP 401 | Do not retry | +| HTTP 403 | Do not retry | +| Validation error | Do not retry | + +### 3.2 Backoff Algorithm + +``` +delay = min(initial_delay * (multiplier ^ attempt) + jitter, max_delay) + +where: + initial_delay = 1000ms + multiplier = 2.0 + jitter = random(-10%, +10%) + max_delay = 30000ms +``` + +### 3.3 Circuit Breaker States + +| State | Condition | Behavior | +|-------|-----------|----------| +| CLOSED | Normal operation | All requests pass | +| OPEN | Failure rate > 50% in 10s | All requests fail fast | +| HALF_OPEN | After 10s in OPEN | Allow 5 test requests | + +--- + +## 4. Observation Points Specification + +### 4.1 Trace Spans + +| Span Name | Parent | Attributes | +|-----------|--------|------------| +| `agent-runtime-request` | Root | request_id, model | +| `connection-acquire` | agent-runtime-request | pool_name, wait_time | +| `request-build` | agent-runtime-request | payload_size | +| `api-call` | agent-runtime-request | endpoint, status_code | +| `retry-attempt-N` | api-call | attempt_num, error | +| `response-parse` | agent-runtime-request | response_size | +| `contract-validate` | agent-runtime-request | result, violations | +| `response-emit` | agent-runtime-request | output_size | + +### 4.2 Metrics + +| Metric | Type | Labels | Description | +|--------|------|--------|-------------| +| `runtime_requests_total` | Counter | model, status | Total requests | +| `runtime_request_duration_seconds` | Histogram | model | Request latency | +| `runtime_connections_active` | Gauge | pool_name | Active connections | +| `runtime_connections_wait_seconds` | Histogram | pool_name | Wait time | +| `runtime_retries_total` | Counter | model, error_type | Retry count | +| `runtime_contract_validations_total` | Counter | result | Validation count | +| `runtime_circuit_breaker_state` | Gauge | circuit_name | CB state (0/1/2) | + +### 4.3 Log Events + +| Event | Level | Fields | +|-------|-------|--------| +| `request_initiated` | INFO | request_id, model, timestamp | +| `request_completed` | INFO | request_id, duration_ms, tokens_used | +| `request_failed` | ERROR | request_id, error_code, error_message | +| `retry_triggered` | WARN | request_id, attempt, error_type, delay_ms | +| `circuit_opened` | ERROR | circuit_name, failure_rate | +| `circuit_closed` | INFO | circuit_name | +| `contract_violation` | ERROR | request_id, violations[] | + +--- + +## 5. Integration Contract + +### 5.1 Component Dependencies + +``` +Client + └── AgentRuntime + ├── MiniMaxConnector + │ └── ConnectionPool + ├── OutputContract + │ ├── SchemaValidator + │ └── TypeCoercer + ├── RetryMechanism + │ ├── RetryPolicy + │ ├── BackoffCalculator + │ └── CircuitBreaker + └── Observability + ├── Tracer + ├── MetricsCollector + └── LogEmitter +``` + +### 5.2 Error Propagation + +| Source | Error Type | Propagation | +|--------|------------|-------------| +| MiniMaxConnector | ConnectionError | RetryMechanism | +| MiniMaxConnector | TimeoutError | RetryMechanism | +| MiniMaxConnector | AuthError | Client (no retry) | +| OutputContract | ValidationError | Client (no retry) | +| CircuitBreaker | OpenError | Client (no retry) | + +--- + +*Specification Version: 1.0* +*Last Updated: 2026-07-10*