AI-Powered Scripts

Add // @ai true to any script and hoody-exec injects the Vercel AI SDK helpers into the script context: generateText, streamText, and generateObject. There is nothing to import, no SDK to set up, and no API key to manage. The helpers reach 300+ models through Hoody AI.

Because a script file is already an HTTP endpoint, any script can serve AI responses over HTTP.

---

The @ai magic comment

Add the @ai magic comment to any script:

// @mode serverless
// @ai true

const { text } = await generateText({
  model,
  prompt: 'Explain quantum computing in one sentence'
});

return { answer: text };

The script now has:

• model: a pre-configured AI model, from @ai-model or the default
• openai: the Vercel AI SDK provider factory (createOpenAI), called as openai(modelId)
• ai: the helper namespace, with ai.generate, ai.stream, and ai.object
• generateText(): returns a complete text response
• streamText(): streams a text response
• generateObject(): returns a structured JSON object

---

AI magic comment reference

Control AI behavior with these magic comments:

Comment	Values	Default	Description
@ai	true | false	true	Enable AI helpers
@ai-model	model name	hoody-ai/hoody-free	Which model to use
@ai-temperature	0 - 2	Provider default	Creativity level (0 = deterministic, 2 = very creative)
@ai-max-tokens	number	Provider default	Maximum response length
@ai-key	string	server-configured	API key override (default from server’s --ai-key flag)

The @ai-model value uses Hoody AI model identifiers in provider/model format:

// @ai-model hoody-ai/hoody-free            // Hoody Free (default)
// @ai-model x-ai/grok-4.5                   // xAI Grok 4.5
// @ai-model moonshotai/kimi-k3              // Moonshot Kimi K3
// @ai-model meta-llama/llama-4-maverick     // Meta Llama 4
// @ai-model deepseek/deepseek-v4-pro        // DeepSeek V4

---

Injected AI helpers

When @ai true is set, these are available in your script:

openai, provider factory

A Vercel AI SDK provider factory (createOpenAI), pre-connected to the Hoody AI gateway (default https://ai.hoody.com/api/v1) with a server-configured API key, so there is no endpoint or key to set up on your side. Call openai('<model-id>') to build a model instance for a model other than the default, then pass it to generateText, streamText, or generateObject.

// @ai true

// Build a model from the provider factory and call the AI SDK
const { text } = await generateText({
  model: openai('deepseek/deepseek-v4-pro'),
  prompt: 'Hello!'
});

return { reply: text };

Note

The injected openai is the Vercel AI SDK provider factory (createOpenAI), not the official openai npm client, so openai.chat.completions.create(...) does not apply. For the official OpenAI SDK, use const OpenAI = require('openai'); it is bundled.

model, pre-configured model

A pre-configured Vercel AI SDK model instance from the @ai-sdk/openai package. Uses the model name from @ai-model (default: hoody-ai/hoody-free). Pass this to generateText, streamText, or generateObject.

// @ai true
// @ai-model deepseek/deepseek-v4-pro

// `model` is already configured with the above model
const { text } = await generateText({ model, prompt: 'Hello!' });

ai, helper namespace

A namespace of three convenience methods over the Vercel AI SDK:

• ai.generate(options) returns a complete text response and wraps generateText
• ai.stream(options) streams text chunks as they are produced and wraps streamText
• ai.object(options) returns structured JSON validated against a schema and wraps generateObject

// @ai true

const { text } = await ai.generate({ prompt: 'Hello!' });
const { textStream } = await ai.stream({ prompt: 'Write a poem' });
const { object } = await ai.object({ schema, prompt: 'Classify this' });

generateText(options), text completion

Generate a complete text response. Returns when the full response is ready.

Options: { prompt?, messages?, model?, system?, temperature?, maxTokens? }

// @ai true
// @ai-model deepseek/deepseek-v4-pro

const { text } = await generateText({
  model,
  prompt: 'Write a haiku about HTTP'
});

return { haiku: text };

streamText(options), streaming responses

Stream response chunks as they are generated. Use it for long responses or real-time UIs.

Options: { prompt?, messages?, model?, system?, temperature?, maxTokens? }

// @ai true
// @ai-model deepseek/deepseek-v4-pro
// @timeout 60000

const { textStream } = await streamText({
  model,
  prompt: req.body.question
});

// Stream back to client
res.writeHead(200, { 'Content-Type': 'text/plain' });
for await (const chunk of textStream) {
  res.write(chunk);
}
res.end();

generateObject(options), structured JSON output

Generate structured JSON that matches a provided schema. The AI response is validated against the schema automatically.

Options: { prompt?, messages?, model?, schema, system?, temperature?, maxTokens? }

// @ai true
// @ai-model deepseek/deepseek-v4-pro

const { object } = await generateObject({
  model,
  schema: {
    type: 'object',
    properties: {
      sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
      confidence: { type: 'number' },
      keywords: { type: 'array', items: { type: 'string' } }
    }
  },
  prompt: `Analyze the sentiment of: "${req.body.text}"`
});

return object;
// → { sentiment: 'positive', confidence: 0.92, keywords: ['great', 'love'] }

---

AI configuration defaults

When @ai true is set, these defaults apply:

Setting	Default	Override
AI URL	https://ai.hoody.com/api/v1	Server-launch --ai-url flag
Model	hoody-ai/hoody-free	@ai-model magic comment
API Key	Server-configured default (via --ai-key flag)	@ai-key magic comment
Temperature	Provider default	@ai-temperature magic comment
Max Tokens	Provider default	@ai-max-tokens magic comment

Override any of them per script with the matching magic comment:

// @ai true
// @ai-model meta-llama/llama-4-maverick
// @ai-key sk-custom-key-here
// @ai-temperature 0.3
// @ai-max-tokens 2048

---

Error handling

AI calls respect the script’s @timeout setting. If the AI provider takes longer than the configured timeout, the request is terminated.

// @ai true
// @timeout 30000  // AI call must complete within 30 seconds

const { text } = await generateText({
  model,
  prompt: req.body.question
});

return { answer: text };

There is no automatic retry for a failed AI call. Implement retry logic in your script if you need it:

// @ai true
// @timeout 60000

async function withRetry(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === retries - 1) throw err;
    }
  }
}

const { text } = await withRetry(() =>
  generateText({ model, prompt: req.body.question })
);

return { answer: text };

---

AI magic comment validation

To validate AI-related magic comments without executing a script, use the magic comments validation endpoint:

curl -s -X POST "https://PROJECT-CONTAINER-exec-1.SERVER.containers.hoody.com/api/v1/exec/validate/magic-comments" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "// @ai true\n// @ai-model meta-llama/llama-4-maverick\n// @ai-temperature 0.5\nreturn {};"
  }'

Retrieve the full magic comments schema, including every @ai-* directive, with:

curl "https://PROJECT-CONTAINER-exec-1.SERVER.containers.hoody.com/api/v1/exec/magic-comments/schema"

---

Example AI endpoints

Text summarizer

api/summarize.ts

// @mode serverless
// @ai true
// @ai-model deepseek/deepseek-v4-pro
// @ai-temperature 0.3
// @cors reflective
// @timeout 30000

if (!req.body?.content) {
  res.statusCode = 400;
  return { error: 'Missing content field' };
}

const { text } = await generateText({
  model,
  prompt: `Summarize the following text in 2-3 sentences:\n\n${req.body.content}`
});

return {
  summary: text,
  originalLength: req.body.content.length,
  summaryLength: text.length
};

Content classifier

api/classify.ts

// @mode serverless
// @ai true
// @ai-model hoody-ai/hoody-free
// @ai-temperature 0
// @cors reflective

const { object } = await generateObject({
  model,
  schema: {
    type: 'object',
    properties: {
      category: { type: 'string', enum: ['bug', 'feature', 'question', 'docs', 'other'] },
      priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
      summary: { type: 'string' }
    }
  },
  prompt: `Classify this support ticket:\n\n${req.body.ticket}`
});

return object;

Streaming chatbot

api/chat.ts

// @mode serverless
// @ai true
// @ai-model deepseek/deepseek-v4-pro
// @ai-temperature 0.7
// @ai-max-tokens 2048
// @cors reflective
// @timeout 60000

const messages = req.body.messages || [];

const { textStream } = await streamText({
  model,
  messages: [
    { role: 'system', content: 'You are a helpful assistant. Be concise.' },
    ...messages
  ]
});

// Stream Server-Sent Events
res.writeHead(200, {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  'Connection': 'keep-alive'
});

for await (const chunk of textStream) {
  res.write(`data: ${JSON.stringify({ text: chunk })}\n\n`);
}

res.write('data: [DONE]\n\n');
res.end();

---

AI MITM pattern

A hoody-exec worker script can act as a MITM (Man-In-The-Middle) proxy for AI requests. Any client pointed at it sends every request through your script, which can intercept, analyze, modify, block, or enhance the interaction.

Deploy the MITM script once, then change one URL in your AI client:

Without MITM: https://ai.hoody.com/api/v1
With MITM:    https://PROJECT_ID-CONTAINER_ID-exec-1.node-us.containers.hoody.com/api/v1

Patterns this enables:

• Tool call tampering: redirect file writes, block dangerous commands
• Human-in-the-loop: pause the AI for approval on high-stakes operations
• Cost optimization: compress prompts, cache responses, route to cheaper models
• Context injection: enhance prompts from your knowledge base automatically
• Observability: log every prompt, response, and decision

Hoody AI Intercept & Control has the complete MITM guide with full examples.

Two MITM patterns, same execution surface

AI MITM, above, is client-initiated: your AI client points its base_url at hoody-exec. Proxy Hooks are proxy-initiated: you register JavaScript handlers in your container’s permissions document, and the Hoody Proxy dispatches matching traffic through hoody-exec on your behalf, for any service and not only AI. Both run inside the same tenant-owned hoody-exec with identical privileges; pick the pattern that matches who decides to intercept.

---

What’s Next

Hoody AI Overview 300+ models, container-native auth, published pricing

Intercept & Control AI Full MITM proxy guide for AI requests

Proxy Hooks Proxy-dispatched MITM for any container service

Magic Comments Reference for every magic comment, including the @ai family

Writing Scripts Script format, variables, and response handling