@browserlessapi/inferlo 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrowserlessAPI (Nero Softwares & IT Services Pvt. Ltd.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# Inferlo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The TypeScript backend framework with built-in AI model support.**
+
+Inferlo is a batteries-included TypeScript backend framework with AI models built into its core. Connect Anthropic, OpenAI, Gemini, DeepSeek, Qwen, local models through Ollama or any OpenAI-compatible server, and call them from any route with one API: automatic fallback between models, typed structured output, streaming, embeddings, and per-user usage and cost tracking. Routing, validation, database, auth, OpenAPI and an MCP server come in the same package, with zero runtime dependencies.
+
+```ts
+import { model, route, t } from "@browserlessapi/inferlo";
+
+export const Ticket = model("tickets", {
+  title: t.string().min(3).max(200),
+  body: t.text(),
+  priority: t.enum(["low", "normal", "urgent"]).default("normal"),
+  ownerId: t.ref("users"),
+});
+
+export const createTicket = route
+  .post("/tickets", { body: Ticket.pick("title", "body"), tool: true })
+  .handle(({ body, user, db }) => db.tickets.insert({ ...body, ownerId: user.id }));
+
+export const triageTicket = route
+  .post("/tickets/:id/triage", { params: t.object({ id: t.uuid() }), auth: "agent" })
+  .handle(async ({ params, db, ai, user }) => {
+    const ticket = await db.tickets.get(params.id);
+    const { object } = await ai.generate({
+      model: "fast",
+      prompt: ticket.body,
+      output: t.object({ priority: Ticket.fields.priority, summary: t.string().max(300) }),
+      for: user.id,
+    });
+    return db.tickets.update(ticket.id, object);
+  });
+```
+
+That one model definition gives you the database table, insert and update validation, TypeScript types, OpenAPI docs, an MCP tool and the AI output schema.
+
+## AI models built in
+
+- **Every major provider, one API.** Anthropic, OpenAI, Gemini, Ollama and any OpenAI-compatible server (DeepSeek, Qwen, Groq, OpenRouter, vLLM and more).
+- **Model aliases with fallback.** Routes ask for `"fast"` or `"smart"`; if the first model is down or rate limited, Inferlo tries the next one.
+- **Typed structured output.** Pass a schema and get validated, typed data back. Invalid answers are repaired automatically.
+- **Tool calling.** Pass routes as `tools` and the model calls them as the current user, with the same auth and validation, a step limit and usage per step.
+- **Streaming.** Send model output to the browser as it is generated with one call.
+- **Images.** Send image URLs or base64 data with a prompt to any vision model.
+- **Embeddings** for search and recommendations.
+- **Usage, cost and budgets.** Every call is tracked per user, so you can bill customers and stop calls when their credits run out.
+- **MCP server.** Mark a route `tool: true` and AI agents can call your API, with the same permissions as any other client.
+- **Background jobs for slow AI work.** Queue a typed job from a route with `ctx.jobs.enqueue(...)` and it runs after the response, with retries, from a Postgres queue shared by every instance (`inferlo worker` runs them in their own process), and schedule jobs with `cron("0 3 * * *", job)`.
+
+## Why Inferlo
+
+| | NestJS | Hono | AdonisJS | Express | **Inferlo** |
+|---|---|---|---|---|---|
+| Batteries included (DB, validation, auth) | Partial | No | Yes | No | **Yes** |
+| Runs on Node, Bun, Deno and edge | No | Yes | No | No | **Yes** |
+| One schema for DB, validation, API docs and AI | No | No | No | No | **Yes** |
+| AI providers, fallback, structured output, streaming in core | No | No | No | No | **Yes** |
+| Built-in MCP server from your routes | No | No | No | No | **Yes** |
+| Token usage tracking and budgets | No | No | No | No | **Yes** |
+| Private routes by default | No | No | No | No | **Yes** |
+| Errors with codes, fixes and docs links | No | No | Partial | No | **Yes** |
+| Zero runtime dependencies | No | Yes | No | No | **Yes** |
+
+## Easy to build with AI coding tools
+
+Inferlo is also designed so AI coding tools (Claude Code, Cursor, Codex, NeonCodex and others) write correct Inferlo code on the first try:
+
+- **Familiar shapes.** Hono-style routes and Zod-style schemas: patterns models already know.
+- **One way to do things.** One route API, one schema API, one query API, one AI API.
+- **No hidden behaviour.** No decorators, no dependency injection, no global registration. Everything a handler needs is in its file.
+- **Types catch invented code.** Misspelled fields, missing tables and wrong types fail at compile time. At runtime, unknown fields are rejected with "Did you mean ...?".
+- **Errors that explain the fix.** Every error has a stable code (`IL1001`), the cause, the fix and a docs link.
+- **Tools for agents.** `inferlo describe --json` returns the whole app map. `inferlo check --json` returns typecheck, load and test results as JSON. `inferlo add resource` generates correct CRUD code.
+- **Docs for machines.** [`llms.txt`](llms.txt), [`llms-full.txt`](llms-full.txt), and every new project ships with `AGENTS.md` and `CLAUDE.md`.
+- **Secure by default.** Routes require a signed-in user unless marked public, every query is parameterised, and every insert is validated, so AI-written code stays safe even with light review.
+
+## Quick start
+
+Requires Node.js 22.18+ or Bun 1.3+. TypeScript runs directly with no build step.
+
+Every release is tested on Node.js 22.18, 22, 24, 26 and the current release; Bun 1.3.0 and latest; PostgreSQL 14, 15, 16, 17, 18 and latest; and TypeScript 5.9 and latest.
+
+```bash
+npx @browserlessapi/inferlo new my-app
+cd my-app && npm install && npm run dev
+```
+
+Or add it to an existing project:
+
+```bash
+npm install @browserlessapi/inferlo
+```
+
+## Features
+
+- **Routing:** `route.get/post/put/patch/delete`, typed path params, query coercion, CORS, middleware, body limits
+- **Schemas:** `t.string()`, `t.email()`, `t.enum()`, `t.ref()`, ... with `.optional()`, `.default()`, `.pick()`, `.partial()`, JSON Schema output
+- **Database:** typed tables (`db.tickets.findMany(...)`), PostgreSQL and in-memory adapters, `inferlo db push`, versioned migrations (`inferlo db migrate`), transactions, unique and foreign keys
+- **Auth:** `auth.resolve(req)`, `bearer()` API keys, roles, password hashing with Web Crypto
+- **AI:** Anthropic, OpenAI, Gemini, Ollama and any OpenAI-compatible server; aliases with fallback; structured output with automatic repair; streaming to SSE; embeddings; per-user usage and cost tracking; budgets
+- **MCP:** routes with `tool: true` become MCP tools at `/mcp`, with the same auth as HTTP
+- **OpenAPI 3.1** at `/openapi.json`
+- **Testing:** `app.request(path, { json, as: user })`, `mockProvider()`, `memory()`
+- **CLI:** `new`, `dev`, `describe`, `check`, `db push`, `db migrate`, `openapi`, `add resource`
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Schemas](docs/schema.md)
+- [Models and database](docs/database.md)
+- [Routes](docs/routes.md)
+- [Auth](docs/auth.md)
+- [AI](docs/ai.md)
+- [MCP, OpenAPI and describe](docs/mcp.md)
+- [CLI](docs/cli.md)
+- [Testing](docs/testing.md)
+- [Deployment](docs/deploy.md)
+- [Error codes](docs/errors.md)
+- [Example: helpdesk with AI triage](examples/helpdesk)
+
+## Status
+
+Inferlo is at **v0.1**. The core API is usable and tested on Node and Bun with PostgreSQL. See [ROADMAP.md](ROADMAP.md) for what is next and [CHANGELOG.md](CHANGELOG.md) for what changed.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). AI agents working on this repository: read [AGENTS.md](AGENTS.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/ai/index.d.ts

@@ -0,0 +1,138 @@
+import { type AnySchema, type Infer } from "../schema.ts";
+import type { RouteDef } from "../route.ts";
+import { type Image, type Message, type Provider, type ProviderUsage, type ToolSpec } from "./providers.ts";
+export * from "./providers.ts";
+export interface Pricing {
+    /** USD per million input tokens. */
+    input: number;
+    /** USD per million output tokens. */
+    output: number;
+}
+export interface Usage {
+    /** Alias or model id you asked for. */
+    requested: string;
+    /** "provider:model" that actually answered. */
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** USD, when pricing is configured for the model. Otherwise 0. */
+    cost: number;
+    /** Who to bill: the userId / tenant you passed as `for`. */
+    for?: string;
+    kind: "generate" | "stream" | "embed";
+    durationMs: number;
+}
+export interface AIConfig {
+    /** Named providers: { anthropic: anthropic({...}), local: ollama() }. */
+    providers: Record<string, Provider>;
+    /** Aliases to "provider:model" ids. A list means fallback order. */
+    models?: Record<string, string | string[]>;
+    /** Alias or id used when a call does not name a model. */
+    defaultModel?: string;
+    /** Prices per model id ("anthropic:claude-haiku-4-5") for cost tracking. Inferlo ships no prices because they change. */
+    pricing?: Record<string, Pricing>;
+    /** Called after every call. Store it, bill it, log it. */
+    onUsage?: (usage: Usage) => void | Promise<void>;
+    /**
+     * Called before a call that has `for` set. Return false (or throw) to block it,
+     * e.g. when a user has used up their credits. Blocked calls raise IL5004 (HTTP 402).
+     */
+    allow?: (info: {
+        for: string;
+        model: string;
+    }) => boolean | Promise<boolean>;
+}
+export interface GenerateOptions<O extends AnySchema | undefined> {
+    /** Alias ("fast") or "provider:model". */
+    model?: string;
+    /** Shorthand for a single user message. */
+    prompt?: string;
+    /** Images for the prompt message: [{ url: "https://..." }] or [{ base64, mediaType: "image/png" }]. Needs a vision model. */
+    images?: Image[];
+    system?: string;
+    messages?: Message[];
+    /** Schema for structured output. The result's `object` is validated and typed. */
+    output?: O;
+    temperature?: number;
+    maxTokens?: number;
+    /** Who this call is for (user or tenant id), for usage tracking and budgets. */
+    for?: string;
+    signal?: AbortSignal;
+    /** Extra attempts when structured output does not match the schema (default 1). */
+    repairAttempts?: number;
+    /**
+     * Routes the model may call as tools, with the current user's permissions:
+     * ctx.ai.generate({ prompt, tools: [createTicket, getTicket] }). Only inside a route handler.
+     */
+    tools?: readonly RouteDef[];
+    /** Most model calls when tools are given: tool rounds plus the final answer (default 5). More raises IL5010. */
+    maxSteps?: number;
+}
+/** One tool call the model made, with what the route returned. */
+export interface ToolCallResult {
+    id: string;
+    /** Tool name: the route's export name (createTicket). */
+    name: string;
+    input: unknown;
+    /** HTTP status the route answered with. */
+    status: number;
+    /** Parsed JSON response (or text), exactly what the model saw. */
+    output: unknown;
+    /** True when the route answered with an error status. */
+    isError: boolean;
+}
+/** One model call. */
+export interface Step {
+    text: string;
+    /** Tools the model called in this step (empty for the final answer). */
+    toolCalls: ToolCallResult[];
+    usage: ProviderUsage;
+}
+export interface GenerateResult<O> {
+    text: string;
+    object: O;
+    /** Totals over every step. */
+    usage: Usage;
+    /** Every model call in order, with tool calls and usage per step. */
+    steps: Step[];
+}
+/** Runs one tool call for the current request. Set by createApp for ctx.ai. */
+export type ToolRunner = (route: RouteDef, input: unknown) => Promise<{
+    name: string;
+    status: number;
+    output: unknown;
+    text: string;
+}>;
+/** ctx.ai for one request: the same AI, with tools that run as the request's user. Internal: used by createApp. */
+export declare function bindTools(ai: AI, runner: ToolRunner, describe: (route: RouteDef) => ToolSpec): AI;
+export interface StreamResult {
+    /** Text chunks as they arrive. */
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    /** Full text once the stream finishes. */
+    text(): Promise<string>;
+    /** A server-sent events Response for browsers (events: "text", then "done" with usage). */
+    toResponse(init?: ResponseInit): Response;
+    /** Usage once the stream finishes. */
+    usage(): Promise<Usage>;
+}
+export interface AI {
+    generate<O extends AnySchema | undefined = undefined>(options: GenerateOptions<O>): Promise<GenerateResult<O extends AnySchema ? Infer<O> : undefined>>;
+    stream(options: Omit<GenerateOptions<undefined>, "output" | "tools" | "maxSteps">): StreamResult;
+    embed(options: {
+        model?: string;
+        input: string | string[];
+        for?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        embeddings: number[][];
+        usage: Usage;
+    }>;
+    /** Configured aliases, for describe(). */
+    readonly aliases: Record<string, string[]>;
+    readonly configured: boolean;
+}
+/** Pull a JSON value out of model text, tolerating ```json fences and leading prose. */
+export declare function extractJson(text: string): unknown;
+export declare function createAI(config?: AIConfig): AI;
+/** Cosine similarity of two vectors, for small in-memory searches. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;