@tagna/udiot

AI-native TypeScript framework for middleware pipelines, dependency injection, state management, typed web apps, and Express-compatible server helpers.

@tagna/udiot provides:

• Typed middleware pipelines
• Decorator-based dependency injection
• Agent runtime primitives for observable LLM calls and tool-using agents
• Caching and telemetry primitives
• Structured run-event telemetry for long-running AI workflows
• State management utilities
• A typed web application layer under @tagna/udiot/web
• Express-oriented server helpers under @tagna/udiot/server
• Server-Sent Events helpers for browser live updates
• Workspace filesystem abstraction for local and sandboxed code generation
• A performance-focused database layer under @tagna/udiot/database

Installation

Requirements:

• Node.js >=20
• npm >=9

npm install @tagna/udiot

Entry Points

• @tagna/udiot for the main framework APIs
• @tagna/udiot/agents for LLMClient, AgentRunner, AgentLoop, and tool registries
• @tagna/udiot/sandbox for WorkspaceFS, local workspaces, and remote sandbox clients
• @tagna/udiot/telemetry for metrics, tracing, logging, AI observability, and run-event streams
• @tagna/udiot/browser for browser-oriented state and UI usage
• @tagna/udiot/database for MikroORM, DbContext-style patterns, and DI-friendly repositories
• @tagna/udiot/database/browser for Supabase and Firebase client helpers
• @tagna/udiot/node for Node-specific utilities
• @tagna/udiot/dev for development tooling
• @tagna/udiot/ssg for static generation
• @tagna/udiot/web for typed app/page contracts, web building, server bootstrap, and diagnostics
• @tagna/udiot/server for Express, sessions, uploads, CSRF, request-scoped DI, and controller adapters

Agent Runtime

@tagna/udiot/agents is the v0.16 runtime for observable LLM calls and multi-step agents. It includes OpenAI and Anthropic providers, retry/backoff, cost tracking, streaming, structured JSON output, tool-use loops, and run-event telemetry. Anthropic support is an optional peer dependency; install @anthropic-ai/sdk in the consuming app before using provider: 'anthropic'.

import { AgentRunner, createLLMClient } from '@tagna/udiot/agents';
import { z } from 'zod';

const llm = createLLMClient({ provider: 'openai' });

const summarizer = new AgentRunner({
  name: 'summarizer',
  systemPrompt: 'Return a compact summary.',
  outputSchema: z.object({ summary: z.string() }),
  model: 'gpt-4o-mini',
  llm,
});

const result = await summarizer.run('UDIOT 0.16 adds agent runtime support.');
console.log(result.output.summary);

The old root-level AIClient remains available for compatibility, but new code should use createLLMClient() and the agent APIs.

Middleware Pipeline

import { MiddlewarePipeline } from '@tagna/udiot';

interface AppContext {
  request: { path: string };
  response?: { message: string };
}

const pipeline = new MiddlewarePipeline<AppContext>();

pipeline.use(async (ctx, next) => {
  await next();
});

pipeline.use(async (ctx, next) => {
  ctx.response = { message: 'Hello from UDIOT' };
  await next();
});

const ctx: AppContext = { request: { path: '/hello' } };
await pipeline.execute(ctx);

Dependency Injection

Import reflect-metadata once before using decorators.

import 'reflect-metadata';
import { Container, Injectable } from '@tagna/udiot';

@Injectable()
class UserService {
  findById(id: string) {
    return { id, name: 'Alice' };
  }
}

const container = new Container();
container.register(UserService);

const userService = container.resolve<UserService>(UserService);
console.log(userService.findById('123'));

Express Server Helpers

import 'reflect-metadata';
import express from 'express';
import { Container, Controller, Get, Param } from '@tagna/udiot';
import {
  createRequestScopeMiddleware,
  createSessionMiddleware,
  toExpressRouter,
} from '@tagna/udiot/server';

@Controller('/posts')
class PostsController {
  @Get('/:id')
  show(@Param('id') id: string) {
    return { id };
  }
}

const app = express();
const container = new Container();
container.register(PostsController);

const sessionSecret = process.env.SESSION_SECRET;
if (!sessionSecret) {
  throw new Error('SESSION_SECRET is required');
}

app.use(express.json());
app.use(createSessionMiddleware({ secret: sessionSecret }));
app.use(createRequestScopeMiddleware({ container }));
app.use(toExpressRouter(PostsController, { container }));

createSessionMiddleware refuses to start in production (NODE_ENV=production) when the secret is well-known (change-me, secret, …), shorter than 32 characters, or when no persistent store is provided. Generate a secret with openssl rand -hex 32 and inject it via the environment.

The server module also exports:

• createNunjucksEngine()
• createEventStream()
• csrfMiddleware()
• flashMiddleware()
• createUploadMiddleware()
• expressCacheMiddleware()
• param()

Example Server-Sent Events stream:

import express from 'express';
import { createEventStream } from '@tagna/udiot/server';

const app = express();
const runs = createEventStream({ channel: 'runs' });

app.get('/events/runs', runs.handler);
await runs.publish({ runId: 'run_123', status: 'started' }, 'run');

Database

@tagna/udiot/database adds a DI-friendly database surface built around MikroORM. It keeps SQL access outside the framework core, but integrates cleanly with request-scoped containers and repository injection.

import 'reflect-metadata';
import { Injectable, ServiceScope } from '@tagna/udiot';
import {
  Entity,
  MikroORM,
  PrimaryKey,
  Property,
  InjectRepository,
  registerMikroOrm,
  type EntityRepository,
} from '@tagna/udiot/database';

@Entity()
class User {
  @PrimaryKey()
  id!: number;

  @Property()
  email!: string;
}

@Injectable({ scope: ServiceScope.SCOPED })
class UserService {
  constructor(
    @InjectRepository(User) private readonly users: EntityRepository<User>,
  ) {}

  list(): Promise<User[]> {
    return this.users.findAll();
  }
}

CLI

The package ships with a udiot binary:

npx udiot --help

Documentation

• Documentation index
• Installation guide
• Web application overview
• Agent runtime
• Run-event telemetry
• Server-Sent Events
• WorkspaceFS sandbox abstraction
• Server module overview
• Database module overview
• Dependency injection docs
• Migration from Express

License

MIT