Reasoning

v0.1.0

Submit thinking requests and let the platform route to the best model for the job

Typescript

bash
npm install @human/client-sdk

Think

Submit a high-level reasoning request with automatic model routing. The service selects the best model based on the requested complexity, budget limit, and optional preferred_model hint. Returns the generated response along with cost and performance metadata.

ParameterDescription
requestReasoning request parameters
typescript
const result = await client.reasoning.think({
  prompt: 'What are the implications of this policy change?',
  complexity: 'medium',
  budget_limit: 10,
});
console.log(result.response);
console.log(`Model: ${result.model_used}, Cost: ${result.cost}`);

Returns: Think response with generated text and metadata

Errors

ValidationError — If request is invalid

RateLimitError — If budget limit is exceeded

List Models

List all available reasoning models. Returns the full catalogue of models registered with the reasoning service, including their capabilities, token limits, and cost rates.

typescript
const models = await client.reasoning.listModels();
for (const model of models) {
  console.log(`${model.name} (${model.provider}) - ${model.performance_tier}`);
}

Returns: Array of available reasoning models

Get Performance

Get performance statistics for a specific model. Returns aggregated metrics including average latency, token usage, success rate, cost per request, and a breakdown by complexity level.

ParameterDescription
modelIdThe model identifier to query
typescript
const perf = await client.reasoning.getPerformance('claude-opus-4-6');
console.log(`Avg latency: ${perf.avg_latency_ms}ms`);
console.log(`Success rate: ${(perf.success_rate * 100).toFixed(1)}%`);

Returns: Performance statistics for the model

Errors

NotFoundError — If modelId does not match a registered model

Submit Benchmark

Submit benchmark results for a model. Sends a prompt/expected-output pair to the service for scoring. Benchmark results feed back into the routing algorithm so that model selection improves over time.

ParameterDescription
requestBenchmark submission parameters
typescript
const result = await client.reasoning.submitBenchmark({
  model_id: 'claude-opus-4-6',
  prompt: 'What is 2+2?',
  expected_output: '4',
  complexity: 'low',
});
console.log(`Score: ${result.score}, Latency: ${result.latency_ms}ms`);

Returns: Benchmark scoring result

Errors

ValidationError — If request is invalid

NotFoundError — If model_id does not match a registered model

Types

typescript
interface ThinkRequest {
  /** The prompt to reason about */
  prompt: string;
  /** Optional context key-value pairs available to the model */
  context?: Record<string, unknown>;
  /** Maximum cost budget for this request (in credits) */
  budget_limit?: number;
  /** Preferred model identifier — treated as a hint, not a guarantee */
  preferred_model?: string;
  /** Complexity level — drives model selection and routing */
  complexity?: Complexity;
  /** Desired response format */
  response_format?: ResponseFormat;
}


interface ThinkResponse {
  /** The generated response text (or JSON string when response_format is 'json') */
  response: string;
  /** Identifier of the model that fulfilled the request */
  model_used: string;
  /** Total tokens consumed (prompt + completion) */
  tokens_used: number;
  /** Cost in credits for this request */
  cost: number;
  /** Optional step-by-step reasoning trace for transparency */
  reasoning_trace?: string[];
  /** Wall-clock duration of the request in milliseconds */
  duration_ms: number;
}


interface ReasoningModel {
  /** Unique model identifier */
  id: string;
  /** Human-readable model name */
  name: string;
  /** Provider that hosts this model (e.g. 'anthropic', 'openai') */
  provider: string;
  /** Capability tags describing what this model excels at */
  capabilities: string[];
  /** Maximum token window for this model */
  max_tokens: number;
  /** Cost in credits per 1 000 tokens */
  cost_per_1k_tokens: number;
  /** Performance tier used for routing (e.g. 'standard', 'premium', 'economy') */
  performance_tier: string;
}


interface ModelPerformance {
  /** Model identifier these stats belong to */
  model_id: string;
  /** Time period these stats cover (e.g. '24h', '7d', '30d') */
  period: string;
  /** Average latency in milliseconds across all requests */
  avg_latency_ms: number;
  /** Average tokens consumed per request */
  avg_tokens: number;
  /** Fraction of requests that completed successfully (0-1) */
  success_rate: number;
  /** Average cost in credits per request */
  cost_per_request: number;
  /** Average latency broken down by complexity level */
  by_complexity: Record<string, number>;
}


interface BenchmarkRequest {
  /** Model identifier to benchmark */
  model_id: string;
  /** The prompt used in the benchmark run */
  prompt: string;
  /** The expected (ground truth) output for scoring */
  expected_output: string;
  /** Complexity level of this benchmark case */
  complexity: Complexity;
}


interface BenchmarkResult {
  /** Quality score (0-1) comparing actual output to expected */
  score: number;
  /** Latency of the benchmark run in milliseconds */
  latency_ms: number;
  /** Tokens consumed during the benchmark run */
  tokens_used: number;
}