@tanvir1971/core 1.0.0

package/dist/telemetry.d.ts

@@ -0,0 +1,76 @@
+/**
+ * OpenTelemetry bootstrap shared by all TypeScript services.
+ * Exports OTLP/HTTP when OTEL_EXPORTER_OTLP_ENDPOINT is configured;
+ * otherwise tracing stays inert so local dev and tests stay quiet.
+ */
+import { type Span, type Tracer, type ContextAPI } from "@opentelemetry/api";
+export type { Tracer };
+export interface TelemetryOptions {
+    serviceName: string;
+    serviceVersion: string;
+    otlpEndpoint?: string;
+}
+export interface TelemetryHandle {
+    tracer: Tracer;
+    shutdown: () => Promise<void>;
+}
+export declare function initTelemetry(options: TelemetryOptions): TelemetryHandle;
+/** Test/dev helper: logs spans to stdout. Never enable in production. */
+export declare function initConsoleTelemetry(options: TelemetryOptions): TelemetryHandle;
+/**
+ * Wraps an async operation in a span with error status recording.
+ * Keeps services free of manual span boilerplate.
+ */
+export declare function withSpan<T>(tracer: Tracer, name: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Gen-AI + Axiom semantic-convention attribute names (O1). Every LLM call in
+ * every service uses these exact keys so the ops plane can reconstruct a
+ * request journey (tokens, cost, cache outcome) from ClickHouse traces.
+ */
+export declare const llmAttr: {
+    readonly system: "gen_ai.system";
+    readonly requestModel: "gen_ai.request.model";
+    readonly responseModel: "gen_ai.response.model";
+    readonly inputTokens: "gen_ai.usage.input_tokens";
+    readonly outputTokens: "gen_ai.usage.output_tokens";
+    readonly totalTokens: "gen_ai.usage.total_tokens";
+    readonly temperature: "gen_ai.request.temperature";
+    readonly maxTokens: "gen_ai.request.max_tokens";
+    readonly finishReason: "gen_ai.response.finish_reason";
+};
+export declare const axiomAttr: {
+    readonly tenantId: "axiom.tenant.id";
+    readonly projectId: "axiom.project.id";
+    readonly requestId: "axiom.request.id";
+    readonly costUsd: "axiom.cost.usd";
+    readonly cacheHit: "axiom.cache.hit";
+    readonly experimentId: "axiom.experiment.id";
+    readonly experimentVariant: "axiom.experiment.variant";
+};
+export type SpanAttributeValue = string | number | boolean;
+export interface LlmCallOutcome {
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    responseModel?: string;
+    finishReason?: string;
+    costUsd?: number;
+}
+/**
+ * Wraps an LLM call in a span carrying Gen-AI attributes; usage/cost
+ * recorded on the same span once the call resolves.
+ */
+export declare function withLlmSpan<T>(tracer: Tracer, name: string, attributes: Record<string, SpanAttributeValue>, fn: (span: Span) => Promise<{
+    value: T;
+    outcome?: LlmCallOutcome;
+}>): Promise<T>;
+/** Re-exported so services do not take direct OTel API dependencies. */
+export declare const otel: {
+    trace: import("@opentelemetry/api").TraceAPI;
+    context: ContextAPI;
+    propagation: import("@opentelemetry/api").PropagationAPI;
+};
+export type { ContextAPI };
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAyB,KAAK,MAAM,EAAW,KAAK,UAAU,EAAe,MAAM,oBAAoB,CAAC;AAE1H,YAAY,EAAE,MAAM,EAAE,CAAC;AAWvB,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAID,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAuCxE;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAW/E;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACrD,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;CAUV,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;;;;CAQZ,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC,GAClE,OAAO,CAAC,CAAC,CAAC,CAqCZ;AAED,wEAAwE;AACxE,eAAO,MAAM,IAAI;;;;CAAkC,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/dist/telemetry.js

@@ -0,0 +1,155 @@
+/**
+ * OpenTelemetry bootstrap shared by all TypeScript services.
+ * Exports OTLP/HTTP when OTEL_EXPORTER_OTLP_ENDPOINT is configured;
+ * otherwise tracing stays inert so local dev and tests stay quiet.
+ */
+import { SpanStatusCode, trace, context, propagation } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { Resource } from "@opentelemetry/resources";
+import { BasicTracerProvider, BatchSpanProcessor, ConsoleSpanExporter, } from "@opentelemetry/sdk-trace-base";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+const handles = new Map();
+export function initTelemetry(options) {
+    const existing = handles.get(options.serviceName);
+    if (existing) {
+        return existing;
+    }
+    const resource = new Resource({
+        [ATTR_SERVICE_NAME]: options.serviceName,
+        [ATTR_SERVICE_VERSION]: options.serviceVersion,
+    });
+    const exporter = options.otlpEndpoint !== undefined
+        ? new OTLPTraceExporter({ url: `${options.otlpEndpoint.replace(/\/$/, "")}/v1/traces` })
+        : undefined;
+    const provider = new BasicTracerProvider({ resource });
+    if (exporter) {
+        provider.addSpanProcessor(new BatchSpanProcessor(exporter));
+    }
+    provider.register({
+        // W3C trace-context propagation is required for O6 cross-service
+        // correlation: without a registered propagator the OTel API defaults to
+        // NoopTextMapPropagator and traceparent headers are never injected or
+        // extracted.
+        propagator: new W3CTraceContextPropagator(),
+    });
+    const tracer = trace.getTracer(options.serviceName, options.serviceVersion);
+    const handle = {
+        tracer,
+        shutdown: async () => {
+            await provider.shutdown();
+            handles.delete(options.serviceName);
+        },
+    };
+    handles.set(options.serviceName, handle);
+    return handle;
+}
+/** Test/dev helper: logs spans to stdout. Never enable in production. */
+export function initConsoleTelemetry(options) {
+    const provider = new BasicTracerProvider({
+        resource: new Resource({
+            [ATTR_SERVICE_NAME]: options.serviceName,
+            [ATTR_SERVICE_VERSION]: options.serviceVersion,
+        }),
+    });
+    provider.addSpanProcessor(new BatchSpanProcessor(new ConsoleSpanExporter()));
+    provider.register();
+    const tracer = trace.getTracer(options.serviceName, options.serviceVersion);
+    return { tracer, shutdown: () => provider.shutdown() };
+}
+/**
+ * Wraps an async operation in a span with error status recording.
+ * Keeps services free of manual span boilerplate.
+ */
+export async function withSpan(tracer, name, attributes, fn) {
+    return tracer.startActiveSpan(name, { attributes }, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Gen-AI + Axiom semantic-convention attribute names (O1). Every LLM call in
+ * every service uses these exact keys so the ops plane can reconstruct a
+ * request journey (tokens, cost, cache outcome) from ClickHouse traces.
+ */
+export const llmAttr = {
+    system: "gen_ai.system",
+    requestModel: "gen_ai.request.model",
+    responseModel: "gen_ai.response.model",
+    inputTokens: "gen_ai.usage.input_tokens",
+    outputTokens: "gen_ai.usage.output_tokens",
+    totalTokens: "gen_ai.usage.total_tokens",
+    temperature: "gen_ai.request.temperature",
+    maxTokens: "gen_ai.request.max_tokens",
+    finishReason: "gen_ai.response.finish_reason",
+};
+export const axiomAttr = {
+    tenantId: "axiom.tenant.id",
+    projectId: "axiom.project.id",
+    requestId: "axiom.request.id",
+    costUsd: "axiom.cost.usd",
+    cacheHit: "axiom.cache.hit",
+    experimentId: "axiom.experiment.id",
+    experimentVariant: "axiom.experiment.variant",
+};
+/**
+ * Wraps an LLM call in a span carrying Gen-AI attributes; usage/cost
+ * recorded on the same span once the call resolves.
+ */
+export async function withLlmSpan(tracer, name, attributes, fn) {
+    return tracer.startActiveSpan(name, { attributes }, async (span) => {
+        try {
+            const { value, outcome } = await fn(span);
+            if (outcome !== undefined) {
+                if (outcome.usage?.inputTokens !== undefined) {
+                    span.setAttribute(llmAttr.inputTokens, outcome.usage.inputTokens);
+                }
+                if (outcome.usage?.outputTokens !== undefined) {
+                    span.setAttribute(llmAttr.outputTokens, outcome.usage.outputTokens);
+                }
+                if (outcome.usage?.totalTokens !== undefined) {
+                    span.setAttribute(llmAttr.totalTokens, outcome.usage.totalTokens);
+                }
+                if (outcome.responseModel !== undefined) {
+                    span.setAttribute(llmAttr.responseModel, outcome.responseModel);
+                }
+                if (outcome.finishReason !== undefined) {
+                    span.setAttribute(llmAttr.finishReason, outcome.finishReason);
+                }
+                if (outcome.costUsd !== undefined) {
+                    span.setAttribute(axiomAttr.costUsd, outcome.costUsd);
+                }
+            }
+            span.setStatus({ code: SpanStatusCode.OK });
+            return value;
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/** Re-exported so services do not take direct OTel API dependencies. */
+export const otel = { trace, context, propagation };
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Token estimation shared across services (o200k BPE via tiktoken ranks).
+ * Used for pre-flight budgeting where provider-reported usage does not
+ * exist yet.
+ */
+export declare function estimateTokens(text: string): number;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD"}

package/dist/tokens.js

@@ -0,0 +1,15 @@
+/**
+ * Token estimation shared across services (o200k BPE via tiktoken ranks).
+ * Used for pre-flight budgeting where provider-reported usage does not
+ * exist yet.
+ */
+import { Tiktoken } from "js-tiktoken/lite";
+import o200k_base from "js-tiktoken/ranks/o200k_base";
+const ENCODER = new Tiktoken(o200k_base);
+export function estimateTokens(text) {
+    if (text.length === 0) {
+        return 0;
+    }
+    return ENCODER.encode(text).length;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,UAAU,MAAM,8BAA8B,CAAC;AAEtD,MAAM,OAAO,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC;AAEzC,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Canonical domain types shared across every Axiom AI service.
+ * These are the single source of truth for wire shapes; REST handlers,
+ * gRPC messages (proto/axiom/v1), and internal events all map to them.
+ */
+export declare const AXIOM_PROTOCOL_VERSION: "v1";
+export type ChatRole = "system" | "user" | "assistant" | "tool";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+    /** Present when role === "tool": the tool invocation this message responds to. */
+    toolCallId?: string;
+    name?: string;
+    /**
+     * Prompt-cache marker (Anthropic semantics). The gateway translates this
+     * into `cache_control: {"type":"ephemeral"}` content blocks for Anthropic;
+     * OpenAI-family providers cache automatically and ignore it.
+     */
+    cacheControl?: "ephemeral";
+}
+export interface ChatToolDefinition {
+    name: string;
+    description?: string;
+    /** JSON Schema for the tool arguments. */
+    parametersJsonSchema?: Record<string, unknown>;
+}
+export interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    tools?: ChatToolDefinition[];
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    stopSequences?: string[];
+    stream?: boolean;
+    /** Opaque caller identifier propagated into traces. */
+    requestId?: string;
+    /**
+     * OpenAI prompt-cache routing hint (`prompt_cache_key`). Forwarded only
+     * to providers that support it (currently `openai`).
+     */
+    promptCacheKey?: string;
+}
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /**
+     * Prompt-cache accounting (provider-native caching):
+     * - cachedInputTokens: OpenAI `prompt_tokens_details.cached_tokens`
+     * - cacheWriteTokens: Anthropic `cache_creation_input_tokens`
+     * - cacheReadTokens: Anthropic `cache_read_input_tokens`
+     */
+    cachedInputTokens?: number;
+    cacheWriteTokens?: number;
+    cacheReadTokens?: number;
+}
+export interface ChatCompletionResponse {
+    id: string;
+    model: string;
+    created: number;
+    message: ChatMessage;
+    usage: TokenUsage;
+    finishReason: "stop" | "length" | "tool_calls" | "content_filter";
+}
+/** One increment of a streamed completion. */
+export interface ChatCompletionChunk {
+    id: string;
+    model: string;
+    created: number;
+    delta: {
+        role?: ChatRole;
+        content?: string;
+        toolCallId?: string;
+        toolName?: string;
+        toolArgumentsDelta?: string;
+    };
+    finishReason?: ChatCompletionResponse["finishReason"];
+    usage?: TokenUsage;
+}
+export interface ModelCapabilities {
+    contextWindowTokens: number;
+    maxOutputTokens: number;
+    supportsStreaming: boolean;
+    supportsTools: boolean;
+    modalities: Array<"text" | "image" | "audio">;
+}
+export interface ModelInfo extends ModelCapabilities {
+    id: string;
+    provider: ProviderId;
+    /** USD per 1M tokens; used by metering for pre-flight cost estimates. */
+    inputCostPerMillion?: number;
+    outputCostPerMillion?: number;
+}
+export type ProviderId = "openai" | "anthropic" | "gemini" | "groq" | "mistral" | "siliconflow" | "nvidia-nim";
+export interface TenantContext {
+    tenantId: string;
+    projectId: string;
+    /** Entitlements resolved from the API key record. */
+    allowedModels: readonly string[];
+    rateLimitTier: "free" | "pro" | "enterprise";
+}
+/**
+ * Tenant scoping is structural: services derive this from verified JWT
+ * claims. User-supplied filters can never override it (ADR 0004).
+ */
+export interface TenantVectorScope {
+    collection: string;
+    tenantId: string;
+}
+export interface RetrievedChunk {
+    chunkId: string;
+    documentId: string;
+    score: number;
+    text: string;
+    sourceSpan?: {
+        startOffset: number;
+        endOffset: number;
+    };
+    metadata: Record<string, string | number | boolean>;
+}
+export type AxiomWebhookEventType = "agent.run.started" | "agent.run.step" | "agent.run.completed" | "agent.run.failed" | "ingestion.document.completed" | "ingestion.document.failed";
+export interface AxiomWebhookEvent<T = unknown> {
+    id: string;
+    type: AxiomWebhookEventType;
+    createdAt: string;
+    tenantId: string;
+    data: T;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Canonical domain types shared across every Axiom AI service.
+ * These are the single source of truth for wire shapes; REST handlers,
+ * gRPC messages (proto/axiom/v1), and internal events all map to them.
+ */
+export const AXIOM_PROTOCOL_VERSION = "v1";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAa,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const CORE_VERSION = "0.2.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const CORE_VERSION = "0.2.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tanvir1971/core",
+  "version": "1.0.0",
+  "description": "Shared contracts for Axiom AI: canonical types, configuration schemas, crypto signing, error taxonomy, and Protobuf definitions.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "proto",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src test",
+    "format": "prettier --write src test proto",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.57.1",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "@types/pg": "^8.23.1",
+    "pg": "^8.23.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axiom-ai/axiom-core-shared.git"
+  },
+  "keywords": [
+    "llm",
+    "gateway",
+    "rag",
+    "ai",
+    "infrastructure"
+  ]
+}

package/proto/axiom/v1/gateway.proto

@@ -0,0 +1,84 @@
+syntax = "proto3";
+
+package axiom.v1;
+
+// LLM gateway contract. REST/SSE remains the public surface; this proto is the
+// internal service-to-service contract (spec section 3).
+
+message ChatMessage {
+  string role = 1;
+  string content = 2;
+  optional string tool_call_id = 3;
+  optional string name = 4;
+}
+
+message ToolDefinition {
+  string name = 1;
+  optional string description = 2;
+  bytes parameters_json_schema = 3; // serialized JSON Schema
+}
+
+message ChatCompletionRequest {
+  string model = 1;
+  repeated ChatMessage messages = 2;
+  repeated ToolDefinition tools = 3;
+  optional double temperature = 4;
+  optional double top_p = 5;
+  optional uint32 max_tokens = 6;
+  repeated string stop_sequences = 7;
+  bool stream = 8;
+  string request_id = 9;
+  // Verified tenant context; never accepted from callers.
+  TenantContext tenant = 20;
+}
+
+message Usage {
+  uint32 prompt_tokens = 1;
+  uint32 completion_tokens = 2;
+  uint32 total_tokens = 3;
+}
+
+message ChatCompletionResponse {
+  string id = 1;
+  string model = 2;
+  int64 created = 3;
+  ChatMessage message = 4;
+  Usage usage = 5;
+  string finish_reason = 6;
+}
+
+message StreamChunk {
+  string id = 1;
+  string model = 2;
+  int64 created = 3;
+  string delta_role = 4;
+  string delta_content = 5;
+  optional string finish_reason = 6;
+  optional Usage usage = 7;
+}
+
+message ListModelsRequest {}
+
+message ModelInfo {
+  string id = 1;
+  string provider = 2;
+  uint32 context_window_tokens = 3;
+  uint32 max_output_tokens = 4;
+  bool supports_streaming = 5;
+  bool supports_tools = 6;
+}
+
+message ListModelsResponse {
+  repeated ModelInfo models = 1;
+}
+
+message TenantContext {
+  string tenant_id = 1;
+  string project_id = 2;
+}
+
+service GatewayService {
+  rpc ChatCompletion(ChatCompletionRequest) returns (ChatCompletionResponse);
+  rpc ChatCompletionStream(ChatCompletionRequest) returns (stream StreamChunk);
+  rpc ListModels(ListModelsRequest) returns (ListModelsResponse);
+}

package/proto/axiom/v1/knowledge.proto

@@ -0,0 +1,62 @@
+syntax = "proto3";
+
+package axiom.v1;
+
+// Knowledge pipeline contract for ingestion and retrieval.
+
+message DocumentSource {
+  oneof source {
+    bytes inline_content = 1;   // small documents
+    string uri = 2;             // s3:// or https:// location resolved server-side
+  }
+  string content_type = 3;
+  string filename = 4;
+}
+
+message IngestDocumentRequest {
+  DocumentSource source = 1;
+  string tenant_id = 2;        // must match verified JWT claims
+  string project_id = 3;
+  map<string, string> metadata = 4;
+  ChunkingOptions chunking = 5;
+}
+
+message ChunkingOptions {
+  string strategy = 1; // "fixed" | "recursive" | "sentence_window" | "layout"
+  uint32 target_chunk_tokens = 2;
+  uint32 overlap_tokens = 3;
+}
+
+message IngestStatus {
+  string document_id = 1;
+  string state = 2; // "queued" | "parsing" | "chunking" | "embedding" | "indexed" | "failed"
+  uint32 chunks_indexed = 3;
+  optional string error_message = 4;
+}
+
+message RetrieveRequest {
+  string query = 1;
+  string tenant_id = 2;
+  string project_id = 3;
+  uint32 top_k = 4;
+  optional float score_threshold = 5;
+  bool use_cache = 6;
+}
+
+message RetrievedChunk {
+  string chunk_id = 1;
+  string document_id = 2;
+  float score = 3;
+  string text = 4;
+  map<string, string> metadata = 5;
+}
+
+message RetrieveResponse {
+  repeated RetrievedChunk chunks = 1;
+  bool served_from_cache = 2;
+}
+
+service KnowledgeService {
+  rpc IngestDocument(IngestDocumentRequest) returns (stream IngestStatus);
+  rpc Retrieve(RetrieveRequest) returns (RetrieveResponse);
+}