Aviary
Packages

Packages

The full nestjs-agent package set — core, the NestJS module, the model adapter, stores, the React frontend, governed SQL, the dashboard, and the ecosystem glue points.

@dudousxd/nestjs-agent is a monorepo of small, single-purpose packages. -core defines the SPIs and the agentic loop — the mechanism. Everything else either implements one of those SPIs (a model adapter, a store, a dashboard) or consumes the library from an app (the NestJS module, the React frontend). Which tables, which tenant column, which roles, which model — that's policy you supply by installing the right package and configuring it, never by forking the loop.

The map

PackageRole
-coreFramework-agnostic agent loop, tool registry, and the SPIs (ModelProvider, AgentStore, AgentGovernanceQueries, ActorResolver, RolesPolicy, ApprovalPolicy, TokenStreamSink, QuotaProvider, ActionProposalStore, …); subpaths /genui, /genui/builtins, /ag-ui, /guardrails.
(umbrella)NestJS AgentModule + @AiTool + the /agent controllers (incl. agUiAdapter() for AG-UI 1.0 and the action-proposal routes); subpaths /durable (durable runner), /sink-redis, /guardrails, /genui, /media (chat attachments on nestjs-media).
-ai-sdkaiSdkModel(model) / aiSdkModels({ … }) adapt Vercel AI SDK v7 LanguageModels to ModelProvider; aiSdkEmbedding adapts an EmbeddingModel — zero provider code.
-opencodeAn engine that runs the turns on OpenCode 2 instead of the library's loop (engine: openCode({ host })), with an MCP endpoint OpenCode calls back for the module's @AiTools; subpath /durable.
-reactuseAgentChat + styling-agnostic chat components for a browser frontend; subpaths /markdown, /genui, /genui/json-render, /genui/server (server-side component rendering), /media.
-datacreateExecuteSqlTool — governed, read-only SQL as a prebuilt tool.
-ragRetrieval-Augmented Generation — chunking, ingestion, an embedding-backed Retriever, and in-memory + pgvector stores.
-rag-mediaAuto-ingest nestjs-media uploads into agent RAG — extract, chunk, embed, index, owner-scoped, delete-synced.
-mcpMCP client — import an external Model Context Protocol server's tools as governed agent tools (stdio + streamable HTTP).
-mcp-serverMCP server — expose this deployment's tools to an external MCP client, over the agent's own registry and roles policy.
/genuiGenerative UI across the packages — the isomorphic catalog (-core/genui), AgentGenuiModule (nestjs-agent/genui) and GenuiProvider (-react/genui).
-evalsAnswer-quality scoring over stored runs — a Scorer SPI, a resumable batch runner, and rule / statistical / model-graded built-ins.
-dashboardStandalone AI-gateway governance console (bundled SPA + API), no Telescope required.
-store-mikro-ormAgentStore + AgentGovernanceQueries + AgentPricingStore on MikroORM, plus the action-proposal stores, MikroOrmConfirmTokenStore and MikroOrmTokenStreamSink.
-store-drizzleAgentStore + AgentGovernanceQueries + AgentPricingStore on Drizzle, plus the action-proposal stores, DrizzleConfirmTokenStore and DrizzleTokenStreamSink.
-transport-redisRedisTokenStreamSink — a TokenStreamSink over Redis for multi-replica deployments. (A SQL sink from either store package also works, without Redis.)
-telescopeTelescope extension — an "Agent" tab reusing the governance read-model.
-authzPlugs @dudousxd/nestjs-authz into tool authorization as a RolesPolicy.
-codegenEmits api.agent.* into the ecosystem's unified typed client.
-testingIn-memory store/sink/quota + a deterministic fake model for offline tests.

How they layer

-react ──▸ (SSE /agent/chat) ──▸ umbrella (@dudousxd/nestjs-agent) ──▸ -core
-codegen ─▸ (REST /agent/*)  ──┘                                       │
                                                                        │  (SPIs)
        -store-mikro-orm / -store-drizzle ─────────────────────────────┤  AgentStore + AgentGovernanceQueries + AgentPricingStore
                              -ai-sdk ──────────────────────────────────┤  ModelProvider
                              -authz ────────────────────────────────────┤  RolesPolicy
                              -transport-redis (or a store's SQL sink) ────┤  TokenStreamSink
                              -data (createExecuteSqlTool) ───────────────────┤  a read-kind ToolSpec + ToolHandler
                              -rag ─────────────────────────────────────────────┤  Retriever + EmbeddingProvider (RAG tool / inject)
                              -mcp (an external MCP server's tools) ─────────────┤  ToolSpecs + ToolHandlers, HITL-gated by default
                              -mcp-server (this deployment's tools, outward) ───┤  reads the same ToolRegistry + RolesPolicy, over MCP
                              -rag-media (auto-ingest via diagnostics channel) ──┤  feeds -rag's VectorStore, no hard dep
        -dashboard / -telescope ──────────────────────────────────────────────┘  consume AgentGovernanceQueries

-core has no NestJS dependency and defines every contract; the umbrella package owns the NestJS module, controllers and runners. The other NestJS-aware packages (the stores, -authz, -mcp, -mcp-server, -rag-media, -dashboard) only add a module that binds their implementation to an SPI token. Each adapter implements contracts from -core and nothing else: a store package implements the store-side SPIs, the AI SDK adapter ModelProvider and EmbeddingProvider, the authz adapter RolesPolicy. The dashboard and the Telescope extension are peers — both read the same AgentGovernanceQueries read-model and the same aviary:agent:* diagnostics channel, so you can run either, both, or neither.

Core

The loop, the tool registry, and every SPI.

NestJS (umbrella)

AgentModule, @AiTool, the /agent controllers, and /durable.

AI SDK adapter

aiSdkModel — zero provider code for any Vercel AI SDK v7 model.

React

useAgentChat and styling-agnostic chat components.

Data

Governed, read-only SQL as a prebuilt tool.

RAG

Chunking, ingestion, an embedding-backed Retriever, in-memory + pgvector stores.

RAG media

Auto-ingest nestjs-media uploads into agent RAG.

MCP

Import an external MCP server's tools as governed agent tools.

MCP server

Expose this deployment's tools to an external MCP client.

Generative UI

The isomorphic catalog, AgentGenuiModule, and GenuiProvider.

Evals

Answer-quality scoring over stored runs.

Dashboard

The standalone AI-gateway governance console.

Store (MikroORM)

AgentStore + AgentGovernanceQueries + AgentPricingStore on MikroORM.

Store (Drizzle)

AgentStore + AgentGovernanceQueries + AgentPricingStore on Drizzle.

Transport (Redis)

RedisTokenStreamSink for multi-replica token streaming.

Telescope

An 'Agent' tab reusing the governance read-model.

Authz

Ability-aware RolesPolicy via @dudousxd/nestjs-authz.

Codegen

api.agent.* in the unified typed client.

Testing

In-memory store/sink/quota + a deterministic fake model.

Governed SQL

Give the model read-only SQL access without handing it the database — AST-validated single SELECTs, a fail-closed table allowlist, per-tenant rewriting, and a row cap, all before your runner touches the DB.

@dudousxd/nestjs-agent-core

The framework-agnostic agent loop, tool registry, and every SPI a provider, store, or dashboard implements against.

On this page

The mapHow they layer