AI Decorators

AxilJS AI decorators describe AI-powered behavior without coupling application code to a specific model provider.

They declare the capability or constraint an operation requires. An AI consumer can then interpret that metadata and select the appropriate model, provider, safety policy, retrieval pipeline, or resource limits.

This keeps AI semantics in the application contract while allowing the underlying AI infrastructure to evolve independently.

@tAIComplete#

Declares that a method produces its result through LLM completion.

import { tAIComplete } from '@axiljs/decorator'
 
@tAIComplete({
  task: 'summarization',
  temperature: 0.3
})
async summarize(text: string) {}

Tasks#

The task describes the intended AI capability rather than a specific model or vendor.

@tAIEmbed#

Declares that an operation produces embeddings for vector storage or search.

import { tAIEmbed } from '@axiljs/decorator'
 
@tAIEmbed({
  storeIn: 'documents',
  dimensions: 1536
})
async embedDocument(text: string) {}

The metadata describes the embedding requirement and target storage context so an AI consumer can handle the embedding operation.

@tAIRAG#

Declares a retrieval-augmented generation pipeline.

import { tAIRAG } from '@axiljs/decorator'
 
@tAIRAG({
  collection: 'support-docs',
  topK: 5,
  includeSources: true
})
async answerQuestion(question: string) {}

The declaration specifies the retrieval collection, number of results, and whether retrieved sources should be included in the result.

@tAIGuard#

Declares content-safety checks for AI input or output.

import { tAIGuard } from '@axiljs/decorator'
 
@tAIGuard({
  policies: ['toxicity', 'pii', 'jailbreak'],
  action: 'block'
})
async generateContent(prompt: string) {}

Policies#

Actions#

The decorator describes the required safety policy; the AI consumer is responsible for enforcing it.

@tAIModel#

Selects an AI model by capability rather than by vendor or model name.

import { tAIModel } from '@axiljs/decorator'
 
@tAIModel({ capability: 'reasoning' })
async analyze(data: string) {}

Capabilities#

This allows the application to describe the required model capability while leaving model selection to the AI infrastructure.

@tAITokenBudget#

Declares input, output, and cost limits for an AI operation.

import { tAITokenBudget } from '@axiljs/decorator'
 
@tAITokenBudget({
  maxInput: 4000,
  maxOutput: 1000,
  costLimit: 0.05
})
async summarize(text: string) {}

The budget provides explicit resource constraints for AI execution.

Full AI Example#

AI decorators can be composed with HTTP, authentication, quota, caching, and other AxilJS semantics:

import {
  tHttp,
  tAuth,
  tAIGuard,
  tAIModel,
  tAITokenBudget,
  tAIComplete,
  tQuota,
  tCache,
  tBody
} from '@axiljs/decorator'
 
@tHttp({
  method: 'POST',
  path: '/api/ai/summarize'
})
@tAuth({ required: true })
@tAIGuard({
  policies: ['toxicity', 'pii'],
  action: 'block'
})
@tAIModel({
  capability: 'summarization'
})
@tAITokenBudget({
  maxInput: 4000,
  maxOutput: 500
})
@tAIComplete({
  task: 'summarization',
  temperature: 0.3
})
@tQuota({
  resource: 'ai.tokens',
  amount: 1000
})
@tCache({
  key: (text) => `summary:${hash(text)}`,
  ttl: 3600_000
})
async summarize(@tBody('text') text: string) {
  // AI infrastructure consumes the declared metadata.
}

The AI consumer can read the tAI* metadata and orchestrate the provider call, safety checks, budget enforcement, and other declared semantics.

Composable AI Semantics#

AI decorators describe independent concerns:

• tAIComplete defines the AI task.
• tAIModel defines the required model capability.
• tAIGuard defines content-safety requirements.
• tAITokenBudget defines execution limits.
• tAIRAG defines retrieval-augmented generation.
• tAIEmbed defines embedding requirements.

They can also be composed with non-AI decorators such as tAuth, tQuota, tCache, and tHttp.

This gives an AI operation a declarative contract without requiring its business logic to directly encode provider-specific orchestration.

Reference#

AxilJS AI decorators make AI behavior explicit, composable, and provider-independent. The application declares what AI capability it needs; an AI consumer can determine how that capability is fulfilled.