@sriinnu/kosha-discovery 0.5.0

package/dist/server.js

@@ -0,0 +1,320 @@
+/**
+ * kosha-discovery — HTTP API server (Hono-based).
+ *
+ * Exposes the model registry over a lightweight REST API so that
+ * editor extensions, scripts, and other tools can query discovered
+ * models without importing the library directly.
+ *
+ * Routes:
+ *   GET  /api/models                     — List models (query: ?provider, ?originProvider, ?mode, ?capability)
+ *   GET  /api/models/cheapest            — Cheapest eligible models for a role/capability
+ *   GET  /api/models/:idOrAlias/routes   — All provider routes with preferred/direct metadata
+ *   GET  /api/models/:idOrAlias          — Get a single model by ID or alias (+ baseUrl/version)
+ *   GET  /api/roles                      — Provider->model->roles matrix
+ *   GET  /api/providers                  — List all providers (summary)
+ *   GET  /api/providers/:id              — Get a single provider with its models
+ *   POST /api/refresh                    — Trigger re-discovery (body: { provider?: string })
+ *   GET  /api/resolve/:alias             — Resolve an alias to its canonical model ID
+ *   GET  /api/discovery-errors            — Errors from last discovery pass
+ *   GET  /health                         — Health check
+ * @module
+ */
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { registerDiscoveryRoutes } from "./discovery-routes.js";
+import { ModelRegistry } from "./registry.js";
+import { extractModelVersion, normalizeModelId } from "./normalize.js";
+const MODEL_MODES = ["chat", "embedding", "image", "audio", "moderation", "rerank"];
+const PRICE_METRICS = ["input", "output", "blended"];
+function parseMode(value) {
+    if (!value)
+        return undefined;
+    if (MODEL_MODES.includes(value)) {
+        return value;
+    }
+    return undefined;
+}
+function parseNumber(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return undefined;
+    return n;
+}
+function parsePriceMetric(value) {
+    if (!value)
+        return undefined;
+    if (PRICE_METRICS.includes(value)) {
+        return value;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+//  Server factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a Hono application wired to the given {@link ModelRegistry}.
+ *
+ * The returned app is not yet listening — call `serve()` or mount it
+ * inside another Hono app to start accepting requests.
+ *
+ * @param registry - A pre-populated (or lazy) ModelRegistry instance.
+ * @returns A configured Hono app with all kosha REST routes.
+ */
+export function createServer(registry) {
+    const app = new Hono();
+    registerDiscoveryRoutes(app, registry);
+    // ── Model listing & lookup routes ────────────────────────────────
+    //
+    // GET /api/models supports four optional query parameters:
+    //   ?provider=anthropic        — filter by serving-layer provider slug
+    //   ?originProvider=anthropic  — filter by original model creator
+    //   ?mode=chat                 — filter by ModelMode
+    //   ?capability=vision         — filter by capability flag
+    app.get("/api/models", (ctx) => {
+        const provider = ctx.req.query("provider") ?? undefined;
+        const originProvider = ctx.req.query("originProvider") ?? undefined;
+        const mode = parseMode(ctx.req.query("mode"));
+        const capability = ctx.req.query("capability") ?? undefined;
+        const models = registry.models({ provider, originProvider, mode, capability });
+        return ctx.json({
+            models,
+            count: models.length,
+        });
+    });
+    // Ranked cheapest model lookup for routing decisions. Route must be
+    // registered before dynamic /api/models/:idOrAlias.
+    app.get("/api/models/cheapest", (ctx) => {
+        const options = {
+            role: ctx.req.query("role") ?? undefined,
+            capability: ctx.req.query("capability") ?? undefined,
+            provider: ctx.req.query("provider") ?? undefined,
+            originProvider: ctx.req.query("originProvider") ?? undefined,
+            mode: parseMode(ctx.req.query("mode")),
+            limit: parseNumber(ctx.req.query("limit")),
+            priceMetric: parsePriceMetric(ctx.req.query("priceMetric")),
+            inputWeight: parseNumber(ctx.req.query("inputWeight")),
+            outputWeight: parseNumber(ctx.req.query("outputWeight")),
+            includeUnpriced: ctx.req.query("includeUnpriced") === "true",
+        };
+        const result = registry.cheapestModels(options);
+        const message = result.matches.length > 0
+            ? undefined
+            : result.missingCredentials.length > 0
+                ? "No priced models found. Add credentials for one of the missing providers."
+                : "No priced models found for the requested filters.";
+        return ctx.json({
+            ...result,
+            cheapest: result.matches[0] ?? null,
+            message,
+        });
+    });
+    // Provider/model role matrix for assistant planners and model routers.
+    app.get("/api/roles", (ctx) => {
+        const options = {
+            role: ctx.req.query("role") ?? undefined,
+            capability: ctx.req.query("capability") ?? undefined,
+            provider: ctx.req.query("provider") ?? undefined,
+            originProvider: ctx.req.query("originProvider") ?? undefined,
+            mode: parseMode(ctx.req.query("mode")),
+        };
+        const providers = registry.providerRoles(options);
+        const providerIds = options.provider
+            ? [options.provider]
+            : registry.providers_list().map((provider) => provider.id);
+        const modelCount = providers.reduce((sum, provider) => sum + provider.models.length, 0);
+        return ctx.json({
+            providers,
+            count: providers.length,
+            modelCount,
+            missingCredentials: registry.missingCredentialPrompts(providerIds),
+        });
+    });
+    // ── Capability aggregation route ─────────────────────────────────
+    //
+    // Returns a summary of all capabilities across the ecosystem.
+    // Optional ?provider= filter to scope to one provider.
+    app.get("/api/capabilities", (ctx) => {
+        const provider = ctx.req.query("provider") ?? undefined;
+        const caps = registry.capabilities({ provider });
+        const providerIds = provider
+            ? [provider]
+            : registry.providers_list().map((p) => p.id);
+        return ctx.json({
+            capabilities: caps,
+            count: caps.length,
+            missingCredentials: registry.missingCredentialPrompts(providerIds),
+        });
+    });
+    // All provider routes for a single model — must be registered BEFORE the
+    // generic /:idOrAlias route so that Hono matches "/routes" as a literal
+    // segment rather than treating it as a dynamic parameter value.
+    //
+    // Returns the normalized base ID plus every serving-layer ModelCard that
+    // resolves to the same underlying model (direct, openrouter, bedrock, etc.).
+    app.get("/api/models/:idOrAlias/routes", (ctx) => {
+        const idOrAlias = ctx.req.param("idOrAlias");
+        const routes = registry.modelRouteInfo(idOrAlias);
+        if (routes.length === 0) {
+            return ctx.json({ error: "Model not found", id: idOrAlias }, 404);
+        }
+        return ctx.json({
+            model: normalizeModelId(idOrAlias),
+            preferredProvider: routes.find((route) => route.isPreferred)?.provider,
+            routes,
+        });
+    });
+    // Single model lookup — accepts a canonical ID or a short alias
+    app.get("/api/models/:idOrAlias", (ctx) => {
+        const idOrAlias = ctx.req.param("idOrAlias");
+        const model = registry.model(idOrAlias);
+        if (!model) {
+            return ctx.json({ error: "Model not found", id: idOrAlias }, 404);
+        }
+        const provider = registry.provider(model.provider);
+        return ctx.json({
+            ...model,
+            baseUrl: provider?.baseUrl,
+            version: extractModelVersion(model.id),
+            resolvedOriginProvider: model.originProvider ?? model.provider,
+            isDirectProvider: !model.originProvider || model.originProvider === model.provider,
+        });
+    });
+    // ── Provider listing & lookup routes ─────────────────────────────
+    //
+    // The list endpoint returns a lightweight summary (no full model arrays)
+    // to keep payloads small; use /api/providers/:id for the full detail.
+    app.get("/api/providers", (ctx) => {
+        const prompts = registry.missingCredentialPrompts();
+        const promptByProvider = new Map(prompts.map((prompt) => [prompt.providerId, prompt]));
+        const providers = registry.providers_list().map((p) => {
+            const prompt = promptByProvider.get(p.id);
+            return {
+                id: p.id,
+                name: p.name,
+                baseUrl: p.baseUrl,
+                authenticated: p.authenticated,
+                credentialSource: p.credentialSource,
+                modelCount: p.models.length,
+                lastRefreshed: p.lastRefreshed,
+                missingCredentialPrompt: prompt?.message,
+                credentialEnvVars: prompt?.envVars ?? [],
+            };
+        });
+        return ctx.json({
+            providers,
+            count: providers.length,
+            missingCredentials: prompts,
+        });
+    });
+    // Full provider detail including all of its models
+    app.get("/api/providers/:id", (ctx) => {
+        const id = ctx.req.param("id");
+        const provider = registry.provider(id);
+        if (!provider) {
+            return ctx.json({ error: "Provider not found", id }, 404);
+        }
+        const prompt = registry.missingCredentialPrompts([provider.id])[0];
+        return ctx.json({
+            ...provider,
+            missingCredentialPrompt: prompt?.message,
+            credentialEnvVars: prompt?.envVars ?? [],
+        });
+    });
+    // ── Mutation routes ──────────────────────────────────────────────
+    //
+    // POST /api/refresh triggers a fresh discovery pass. Optionally
+    // accepts { provider: "anthropic" } to refresh only one provider.
+    app.post("/api/refresh", async (ctx) => {
+        const body = await ctx.req.json().catch(() => ({}));
+        const providerId = body.provider;
+        try {
+            await registry.refresh(providerId);
+            const providers = registry.providers_list();
+            const totalModels = providers.reduce((sum, p) => sum + p.models.length, 0);
+            return ctx.json({
+                status: "ok",
+                providers: providers.length,
+                models: totalModels,
+                refreshedAt: Date.now(),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return ctx.json({ error: "Refresh failed", message }, 500);
+        }
+    });
+    // ── Alias resolution route ───────────────────────────────────────
+    app.get("/api/resolve/:alias", (ctx) => {
+        const alias = ctx.req.param("alias");
+        const resolved = registry.resolve(alias);
+        return ctx.json({
+            alias,
+            resolved,
+            isAlias: resolved !== alias,
+        });
+    });
+    // ── Discovery error reporting ────────────────────────────────────
+    //
+    // Returns errors from the most recent discovery pass so operators
+    // can diagnose which providers failed and why.
+    app.get("/api/discovery-errors", (ctx) => {
+        const errors = registry.discoveryErrors();
+        return ctx.json({
+            errors,
+            count: errors.length,
+            hasErrors: errors.length > 0,
+        });
+    });
+    // ── Health check ─────────────────────────────────────────────────
+    app.get("/health", (ctx) => {
+        const providers = registry.providers_list();
+        return ctx.json({
+            status: "ok",
+            models: registry.models().length,
+            providers: providers.length,
+            uptime: process.uptime(),
+        });
+    });
+    return app;
+}
+// ---------------------------------------------------------------------------
+//  Standalone server entry point
+// ---------------------------------------------------------------------------
+/**
+ * Boot a standalone kosha API server.
+ *
+ * Runs full discovery, then starts an HTTP listener on the given port.
+ * @param port - TCP port to bind (default `3000`, overridable via `PORT` env var).
+ */
+export async function startServer(port = 3000) {
+    const registry = new ModelRegistry();
+    console.log("Discovering providers and models...");
+    await registry.discover();
+    const providers = registry.providers_list();
+    const totalModels = registry.models().length;
+    console.log(`Found ${totalModels} models from ${providers.length} providers`);
+    const app = createServer(registry);
+    console.log(`\nKosha API server listening on http://localhost:${port}`);
+    console.log(`  GET  http://localhost:${port}/api/models`);
+    console.log(`  GET  http://localhost:${port}/api/models/cheapest`);
+    console.log(`  GET  http://localhost:${port}/api/models/:id/routes`);
+    console.log(`  GET  http://localhost:${port}/api/capabilities`);
+    console.log(`  GET  http://localhost:${port}/api/roles`);
+    console.log(`  GET  http://localhost:${port}/api/providers`);
+    console.log(`  GET  http://localhost:${port}/api/discovery`);
+    console.log(`  GET  http://localhost:${port}/api/discovery/delta`);
+    console.log(`  GET  http://localhost:${port}/api/discovery/watch`);
+    console.log(`  GET  http://localhost:${port}/health`);
+    serve({ fetch: app.fetch, port });
+}
+// ---------------------------------------------------------------------------
+//  Auto-start when executed directly (e.g. `node dist/server.js`)
+// ---------------------------------------------------------------------------
+const isEntryPoint = import.meta.url === `file://${process.argv[1]}`;
+if (isEntryPoint) {
+    const port = parseInt(process.env.PORT || "3000", 10);
+    startServer(port);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/shell-safe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shell safety utilities — input validation for values passed to CLI subprocesses.
+ *
+ * Prevents command injection by rejecting values that contain shell
+ * metacharacters.  Only alphanumeric characters, hyphens, underscores,
+ * and dots are allowed.
+ * @module
+ */
+/**
+ * Validate that a string is safe to pass as a CLI argument.
+ *
+ * @throws {Error} When the value contains characters outside the safe set.
+ */
+export declare function assertSafeShellArg(value: string, label: string): void;
+//# sourceMappingURL=shell-safe.d.ts.map

package/dist/shell-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-safe.d.ts","sourceRoot":"","sources":["../src/shell-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMrE"}

package/dist/shell-safe.js

@@ -0,0 +1,20 @@
+/**
+ * Shell safety utilities — input validation for values passed to CLI subprocesses.
+ *
+ * Prevents command injection by rejecting values that contain shell
+ * metacharacters.  Only alphanumeric characters, hyphens, underscores,
+ * and dots are allowed.
+ * @module
+ */
+const SAFE_CLI_ARG = /^[a-zA-Z0-9._-]+$/;
+/**
+ * Validate that a string is safe to pass as a CLI argument.
+ *
+ * @throws {Error} When the value contains characters outside the safe set.
+ */
+export function assertSafeShellArg(value, label) {
+    if (!SAFE_CLI_ARG.test(value)) {
+        throw new Error(`Unsafe ${label} value: "${value}" — only alphanumeric characters, hyphens, underscores, and dots are allowed`);
+    }
+}
+//# sourceMappingURL=shell-safe.js.map

package/dist/shell-safe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-safe.js","sourceRoot":"","sources":["../src/shell-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEzC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,KAAa;IAC9D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACd,UAAU,KAAK,YAAY,KAAK,8EAA8E,CAC9G,CAAC;IACH,CAAC;AACF,CAAC"}