AI Generation

MolnOS AI Generation enables you to describe what you want to build in natural language, and have AI generate the how—complete with resources (Functions and Sites), IAC configuration, and implementation explanations.

Human-in-the-Loop

AI Generation always requires explicit user approval before applying code. Generated implementations are reviewed, edited, and approved by you before deployment.

Features

Intent-Driven Development

Describe your application’s purpose and requirements in natural language. The AI uses your context’s intent and attributes to generate appropriate implementations.

Multiple AI Providers

Choose from industry-leading AI providers or use local models:

• Anthropic Claude
• OpenAI GPT
• Evroc Think - European sovereign cloud AI (OpenAI-compatible)
• Ollama - Run models locally for privacy and cost savings

Context-Aware Generation

The AI has access to:

• Your context’s existing resources (functions, databases, storage)
• MolnOS schemas and API documentation
• Existing function code for context
• Best practices and security guidelines

Iterative Refinement

Generate, review, provide feedback, and regenerate until the implementation meets your needs. Each iteration builds on previous attempts with your guidance.

Secure by Design

• No eval() or unsafe code patterns
• Validates inputs and sanitizes outputs
• Follows MolnOS security conventions
• Generated code is checked before presentation

Configuration

Basic Setup

Add AI configuration to your molnos.config.json:

{
  "ai": {
    "enabled": true,
    "provider": "anthropic",
    "apiKey": "${ANTHROPIC_API_KEY}",
    "model": "claude-sonnet-4-5",
    "maxTokens": 32000,
    "temperature": 0.7,
    "generationTtlHours": 24
  }
}

Configuration Options

Option	Type	Description	Default
enabled	boolean	Enable AI generation features	false
provider	string	AI provider (anthropic, openai, evroc, ollama)	-
apiKey	string	API key (supports env var substitution, not needed for Ollama)	-
model	string	Model to use	Provider default
baseUrl	string	Custom API endpoint (optional)	Provider default
endpoint	string	Ollama server URL (Ollama only)	http://localhost:11434
maxTokens	number	Maximum tokens for responses	32000
temperature	number	Sampling temperature (0.0-1.0)	0.7
generationTtlHours	number	Hours to keep generations before cleanup	24

Environment Variables

Use environment variable substitution in your config:

{
  "ai": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  }
}

Then set the environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Local Models with Ollama

Run AI models locally using Ollama for privacy, cost savings, and offline operation:

{
  "ai": {
    "enabled": true,
    "provider": "ollama",
    "endpoint": "http://localhost:11434",
    "model": "codellama:13b",
    "maxTokens": 32000,
    "temperature": 0.7
  }
}

Prerequisites:

1. Install Ollama from ollama.ai

2. Pull a code-capable model:

   ollama pull codellama:13b
   # or
   ollama pull deepseek-coder:6.7b
   # or
   ollama pull qwen2.5-coder:7b

3. Ensure Ollama is running (it starts automatically on most systems)

Recommended Models for Code Generation:

• codellama:13b - Good balance of quality and speed
• deepseek-coder:6.7b - Smaller, faster, good for simple tasks
• qwen2.5-coder:7b - Strong code understanding

Configuration Options:

• endpoint - Ollama server URL (defaults to http://localhost:11434)
• model - Model name from ollama list
• No apiKey required for local Ollama instances

Note: Local models may produce different quality results compared to Claude or GPT-4. For best results with Ollama:

• Use larger models (13b+ parameters)
• Provide clear, detailed intents
• Review generated code carefully
• Iterate with specific feedback

User-Provided API Keys

Users can provide their own API keys when making generation requests, bypassing the server configuration:

curl -X POST http://localhost:3000/contexts/my-app/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Build a URL shortener",
    "userApiKey": "sk-ant-..."
  }'

Usage

API Workflow

1. Create a Context with Intent

curl -X POST http://localhost:3000/contexts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "url-shortener",
    "intent": "Build a URL shortener API that creates short codes and redirects users",
    "attributes": {
      "storage": "kv",
      "auth": "apiKey",
      "features": ["analytics", "custom-domains"]
    }
  }'

2. Generate Implementation

curl -X POST http://localhost:3000/contexts/url-shortener/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The AI will:

• Fetch MolnOS schemas to understand available resources
• Query the context for existing resources
• Generate appropriate functions and IAC configuration
• Return a complete implementation with explanation

Response:

{
  "success": true,
  "generation": {
    "id": "gen_a1b2c3d4",
    "contextId": "url-shortener",
    "status": "pending",
    "functions": [
      {
        "name": "shorten",
        "path": "functions/shorten.js",
        "code": "export async function handler(req, context) { ... }"
      },
      {
        "name": "redirect",
        "path": "functions/redirect.js",
        "code": "export async function handler(req, context) { ... }"
      }
    ],
    "iacConfig": {
      "version": "1",
      "context": {
        "name": "url-shortener"
      },
      "resources": {
        "functions": { ... },
        "databases": { ... }
      }
    },
    "explanation": "# URL Shortener Implementation\n\n..."
  }
}

3. Review Generated Code

curl -X GET http://localhost:3000/generations/gen_a1b2c3d4 \
  -H "Authorization: Bearer $TOKEN"

Review the:

• Functions: Check the generated code for correctness
• IAC Config: Verify resource definitions
• Explanation: Understand the implementation decisions

4. Apply or Discard

Apply (deploy the generated code):

curl -X POST http://localhost:3000/generations/gen_a1b2c3d4/apply \
  -H "Authorization: Bearer $TOKEN"

Discard (reject the generation):

curl -X POST http://localhost:3000/generations/gen_a1b2c3d4/discard \
  -H "Authorization: Bearer $TOKEN"

Refine (iterate with feedback):

curl -X POST http://localhost:3000/contexts/url-shortener/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "previousAttemptId": "gen_a1b2c3d4",
    "iterationFeedback": "Add rate limiting to prevent abuse"
  }'

Generation Management

List Generations for a Context

curl -X GET http://localhost:3000/contexts/url-shortener/generations \
  -H "Authorization: Bearer $TOKEN"

Returns all generations (pending, applied, discarded) for the context.

Delete a Generation

curl -X DELETE http://localhost:3000/generations/gen_a1b2c3d4 \
  -H "Authorization: Bearer $TOKEN"

Permanently removes the generation.

Advanced Usage

Providing Existing Code

Help the AI understand your existing implementation by including current files:

curl -X POST http://localhost:3000/contexts/my-app/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "path": "functions/existing.js",
        "content": "export async function handler(req, context) { ... }"
      }
    ]
  }'

Overriding Provider Settings

Use a different provider or model for specific generation:

curl -X POST http://localhost:3000/contexts/my-app/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerOverride": "openai",
    "modelOverride": "gpt-4-turbo"
  }'

Including IAC Configuration

Provide existing IAC to guide generation:

curl -X POST http://localhost:3000/contexts/my-app/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iacConfig": {
      "version": "1",
      "context": {
        "name": "my-app",
        "intent": "My application"
      },
      "resources": {
        "databases": {
          "users": {},
          "sessions": {}
        }
      }
    }
  }'

Best Practices

Write Clear Intents

Be specific about what you want to build:

Good:

{
  "intent": "Build a user authentication API with email/password login, JWT tokens, and password reset functionality"
}

Bad:

{
  "intent": "Handle users"
}

Use Intent Attributes

Provide structured guidance through attributes:

{
  "intent": "Build a blog platform",
  "attributes": {
    "storage": "kv",
    "auth": "jwt",
    "features": ["markdown", "comments", "tags"],
    "rateLimit": 100
  }
}

Review Before Applying

Always review generated code for:

• Security: Check input validation, sanitization
• Logic: Verify business logic correctness
• Performance: Consider scalability implications
• Dependencies: Ensure minimal external dependencies

Iterate When Needed

Don’t expect perfect code on the first try. Use iteration feedback to refine:

1. Generate initial implementation
2. Review and identify issues
3. Provide specific feedback
4. Regenerate with improvements
5. Repeat until satisfied

Keep Generations Organized

• Apply or discard generations promptly
• Use descriptive feedback in iterations
• Delete old generations you won’t use
• Monitor generation TTL (default 24 hours)

Security Considerations

Generated Code Review

MolnOS validates generated code for:

• No eval() or Function() constructor
• No arbitrary file system access
• No shell command execution
• No vm module usage

But you should also review for:

• Business logic correctness
• Proper error handling
• Input validation
• Authentication/authorization

User-Provided API Keys

When users provide their own API keys:

• Keys are not logged or stored
• Keys are only used for that specific request
• Users pay for their own AI usage
• Reduces operational costs

Permissions

AI generation endpoints require appropriate permissions:

• ai.generation.generate - Generate code implementations
• ai.generation.read - View and list generations
• ai.generation.apply - Apply generated code to infrastructure
• ai.generation.discard - Discard a generation
• ai.generation.delete - Delete a generation

Troubleshooting

AI Generation Not Available

Error: AI generation is not enabled

Solution: Check your molnos.config.json:

{
  "ai": {
    "enabled": true,
    "provider": "anthropic",
    "apiKey": "${ANTHROPIC_API_KEY}"
  }
}

Verify environment variable is set:

echo $ANTHROPIC_API_KEY

API Key Authentication Failed

Error: AI provider authentication failed

Solution:

1. Verify API key is correct
2. Check API key permissions
3. Ensure account has available credits
4. Try regenerating the API key

Generation Expired

Error: Generation not found or expired

Solution: Generations expire after generationTtlHours (default 24 hours). Generate again if needed.

Invalid Response Format

Error: Invalid response format from AI

Solution: The AI returned malformed JSON. Try:

1. Regenerating with the same input
2. Simplifying your intent
3. Using a different model
4. Checking provider status

Rate Limiting

If you encounter rate limits:

1. Wait before retrying
2. Use user-provided API keys to distribute load
3. Implement client-side retry logic
4. Consider upgrading your AI provider tier

Limitations

As of Version 1.3.0

• No streaming: Generations complete before returning
• No editing: Can’t edit code in-place (must iterate)
• No multi-context: One context per generation
• No testing: Generated code isn’t automatically tested
• No bundling: External dependencies require manual bundling

Examples

URL Shortener

{
  "name": "url-shortener",
  "intent": "Build a URL shortener that creates short codes, stores mappings, and redirects users. Include analytics for click tracking.",
  "attributes": {
    "storage": "kv",
    "features": ["analytics", "custom-codes"],
    "auth": "optional"
  }
}

Blog Platform

{
  "name": "blog",
  "intent": "Build a blog API with posts, authors, tags, and comments. Support markdown rendering and search.",
  "attributes": {
    "storage": "kv",
    "database": "tables",
    "features": ["markdown", "search", "comments", "tags"],
    "auth": "jwt"
  }
}

Task Management

{
  "name": "tasks",
  "intent": "Build a task management API with projects, tasks, assignments, and due dates. Support team collaboration.",
  "attributes": {
    "database": "tables",
    "features": ["assignments", "notifications", "recurring-tasks"],
    "auth": "jwt",
    "multitenancy": true
  }
}

API Reference

See the OpenAPI Schema for complete API documentation of all AI generation endpoints.

Related Features

• Infrastructure as Code - Deploy generated IAC configurations
• Functions - Understand generated function code
• Configuration - Configure MolnOS settings