Nerva

Composable Agent Primitives

Build your agent system — not the plumbing around it.

What is Nerva?

Nerva is a library — not a server, not a framework. It provides 8 composable primitives that every agent orchestrator needs: routing, execution, tools, memory, response formatting, registry, and policy enforcement. Use one primitive or all eight. Replace any piece with your own implementation. Nerva runs inside your existing web framework (FastAPI, NestJS, Express) and stays invisible to your API consumers.

The 8 Primitives

Each primitive is a Protocol (Python) / interface (TypeScript) with a default implementation. Swap any piece without touching the rest.

The Gap

SDKs are too thin. Pydantic AI, LiteLLM, and similar libraries give you LLM calls and not much else. You still build routing, memory, tool management, and lifecycle from scratch every time.

Frameworks own your architecture. LangGraph, CrewAI, and AutoGen give you everything — but on their terms. Swap a component and you fight the framework.

Nerva is the middle ground. Opinionated primitives, zero opinions on how you compose them. No base classes to inherit, no lifecycle you did not ask for, no magic graph runtime.

Quick Start — Python

pip install otomus-nerva

import asyncio
from nerva import Orchestrator, ExecContext
from nerva.router import RuleRouter, Rule
from nerva.runtime import InProcessRuntime
from nerva.tools import FunctionToolManager
from nerva.memory import TieredMemory
from nerva.responder import PassthroughResponder
from nerva.registry import InMemoryRegistry
from nerva.policy import NoopPolicyEngine

# Define a simple handler
async def greet_handler(input_text: str, ctx: ExecContext) -> str:
    return f"Hello! You said: {input_text}"

# Wire primitives together
orchestrator = Orchestrator(
    router=RuleRouter(rules=[
        Rule(pattern=r".*", handler="greet", description="Catch-all greeter"),
    ]),
    runtime=InProcessRuntime(handlers={"greet": greet_handler}),
    tools=FunctionToolManager(),
    memory=TieredMemory(),
    responder=PassthroughResponder(),
    registry=InMemoryRegistry(),
    policy=NoopPolicyEngine(),
)

async def main():
    ctx = ExecContext.create(user_id="user_1")
    result = await orchestrator.handle("What's the weather?", ctx)
    print(result.text)

asyncio.run(main())

Quick Start — TypeScript

npm install @otomus/nerva

import {
  Orchestrator,
  ExecContext,
  RuleRouter,
  FunctionToolManager,
  TieredMemory,
  InMemoryRegistry,
  NoopPolicyEngine,
} from "@otomus/nerva";

// Define a simple handler
async function greetHandler(input: string, ctx: ExecContext): Promise<string> {
  return `Hello! You said: ${input}`;
}

// Wire primitives together
const orchestrator = new Orchestrator({
  router: new RuleRouter({
    rules: [{ pattern: /.*/, handler: "greet", description: "Catch-all greeter" }],
  }),
  runtime: { invoke: async (handler, input, ctx) => ({ text: await greetHandler(input.query, ctx), status: "success" }) },
  tools: new FunctionToolManager(),
  memory: new TieredMemory(),
  responder: { format: async (output, channel, ctx) => ({ text: output.text }) },
  registry: new InMemoryRegistry(),
  policy: new NoopPolicyEngine(),
});

async function main() {
  const ctx = ExecContext.create({ userId: "user_1" });
  const result = await orchestrator.handle("What's the weather?", ctx);
  console.log(result.text);
}

main();

CLI

Scaffold new projects and generate components:

# Create a new agent project
npx nerva new my-agent --lang python
npx nerva new my-agent --lang typescript

# Generate components inside a project
npx nerva generate agent weather
npx nerva generate tool search
npx nerva generate router custom
npx nerva generate middleware logging

Framework Integration

Nerva is a library layer — like React, not Next.js. It runs inside your web framework.

FastAPI / NestJS / Express  (HTTP, auth, sessions, swagger, CORS)
  └── Nerva                 (agent orchestration: routing, runtime, tools, memory, policy)
       └── LLM providers, MCP servers, subprocess agents

FastAPI

from fastapi import FastAPI, Depends
from nerva import Orchestrator, ExecContext
from nerva.contrib.fastapi import get_nerva_ctx

app = FastAPI(title="My Agent API")
orchestrator = build_orchestrator()

@app.post("/chat", response_model=ChatResponse)
async def chat(req: ChatRequest, ctx: ExecContext = Depends(get_nerva_ctx)):
    response = await orchestrator.handle(req.message, ctx)
    return ChatResponse(text=response.text, tokens=ctx.token_usage.total)

NestJS

import { Controller, Post, Body, UseGuards } from '@nestjs/common';
import { Orchestrator } from '@otomus/nerva';
import { NervaCtx } from '@otomus/nerva/contrib/nestjs';

@Controller('chat')
export class ChatController {
  constructor(private orchestrator: Orchestrator) {}

  @Post()
  @UseGuards(JwtAuthGuard)
  async chat(@Body() dto: ChatDto, @NervaCtx() ctx: ExecContext) {
    return this.orchestrator.handle(dto.message, ctx);
  }
}

Express

import express from 'express';
import { Orchestrator } from '@otomus/nerva';
import { nervaMiddleware } from '@otomus/nerva/contrib/express';

const app = express();
app.use(nervaMiddleware(config));

app.post('/chat', async (req, res) => {
  const response = await orchestrator.handle(req.body.message, req.nervaCtx);
  res.json(response);
});

Comparison

Packages

Package	Description
nerva-py	Python implementation (3.11+)
@otomus/nerva	TypeScript implementation (Node 20+)
@otomus/nerva-cli	CLI for scaffolding and code generation

Links

• Documentation
• Homepage
• Examples
• TypeSpec Schema
• Contributing
• GitHub

License

MIT