AI-Native Architecture: Designing for Intelligence

// prompts/classify-support-ticket.ts
// Treat this as a versioned interface — changes are breaking changes

export const CLASSIFY_TICKET_PROMPT = `You are a customer support classifier for a SaaS product.

Classify the following support ticket into exactly one category:
- billing: questions about invoices, charges, or subscriptions
- technical: bugs, errors, or integration issues
- feature-request: requests for new functionality
- account: login issues, password resets, account settings
- other: anything that does not fit the above

Respond with a JSON object matching this schema exactly:
{
  "category": "<one of the categories above>",
  "confidence": <number between 0 and 1>,
  "reasoning": "<one sentence explanation>"
}

Do not include any text outside the JSON object.

Ticket: {TICKET_CONTENT}`;

export function buildClassifyPrompt(ticketContent: string): string {
  return CLASSIFY_TICKET_PROMPT.replace('{TICKET_CONTENT}', ticketContent);
}

// Structured output with validation
import { z } from 'zod';

const TicketClassificationSchema = z.object({
  category: z.enum(['billing', 'technical', 'feature-request', 'account', 'other']),
  confidence: z.number().min(0).max(1),
  reasoning: z.string()
});

async function classifyTicket(content: string) {
  const response = await anthropic.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: 256,
    messages: [{ role: 'user', content: buildClassifyPrompt(content) }]
  });

  const text = response.content[0].type === 'text' ? response.content[0].text : '';

  // Parse and validate — never trust raw LLM output
  const parsed = JSON.parse(text);
  return TicketClassificationSchema.parse(parsed);
}

Query: "What is the refund policy for annual plans?"
         │
         â–¼
┌──────────────────┐
│  Embedding Model │  Converts query to vector [0.12, -0.34, 0.89, ...]
└──────────────────┘
         │
         â–¼
┌──────────────────┐
│  Vector Database │  Finds top-k most similar document chunks
│  (Pinecone/pgvector)│
└──────────────────┘
         │
         â–¼ Retrieved context chunks
┌──────────────────┐
│  Prompt Builder  │  Injects chunks into system prompt
└──────────────────┘
         │
         â–¼
┌──────────────────┐
│  LLM             │  Answers based on injected context
└──────────────────┘

-- PostgreSQL with pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  source      TEXT NOT NULL,         -- file path or URL
  chunk_index INTEGER NOT NULL,
  content     TEXT NOT NULL,
  embedding   vector(1536),          -- OpenAI text-embedding-3-small dimension
  metadata    JSONB DEFAULT '{}'
);

CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

// Ingest documents
async function ingestDocument(filePath: string, content: string) {
  // Split into chunks (overlap helps with context continuity)
  const chunks = splitIntoChunks(content, { chunkSize: 512, overlap: 50 });

  for (const [index, chunk] of chunks.entries()) {
    const embedding = await openai.embeddings.create({
      model: 'text-embedding-3-small',
      input: chunk
    });

    await db.query(
      `INSERT INTO documents (source, chunk_index, content, embedding)
       VALUES ($1, $2, $3, $4)`,
      [filePath, index, chunk, JSON.stringify(embedding.data[0].embedding)]
    );
  }
}

// Query
async function retrieveContext(query: string, topK = 5): Promise<string[]> {
  const queryEmbedding = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: query
  });

  const results = await db.query<{ content: string }>(
    `SELECT content
     FROM documents
     ORDER BY embedding <=> $1
     LIMIT $2`,
    [JSON.stringify(queryEmbedding.data[0].embedding), topK]
  );

  return results.rows.map(r => r.content);
}

// Augmented generation
async function answerWithContext(question: string): Promise<string> {
  const contexts = await retrieveContext(question);

  const response = await anthropic.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: 1024,
    system: `You are a helpful assistant. Answer based only on the provided context.
If the context does not contain the answer, say so explicitly.

Context:
${contexts.map((c, i) => `[${i + 1}] ${c}`).join('\n\n')}`,
    messages: [{ role: 'user', content: question }]
  });

  return response.content[0].type === 'text' ? response.content[0].text : '';
}

User: "Find all open GitHub issues assigned to alice and create a summary report"
         │
         â–¼ Reasoning
Agent: "I need to call the GitHub API to get issues. I'll use the list_issues tool."
         │
         â–¼ Action
Tool call: github.issues.list({ assignee: 'alice', state: 'open' })
         │
         â–¼ Observation
Returns: [{ id: 1, title: "Login bug", ... }, { id: 2, title: "API timeout", ... }]
         │
         â–¼ Reasoning
Agent: "I have the issues. Now I'll format them into a report."
         │
         â–¼ Final response: "Alice has 2 open issues: ..."

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: 'get_database_stats',
    description: 'Get current database metrics including connection count, query latency, and table sizes',
    input_schema: {
      type: 'object' as const,
      properties: {
        database_name: {
          type: 'string',
          description: 'Name of the database to query'
        }
      },
      required: ['database_name']
    }
  },
  {
    name: 'create_alert',
    description: 'Create a PagerDuty alert for a critical issue',
    input_schema: {
      type: 'object' as const,
      properties: {
        severity: { type: 'string', enum: ['critical', 'high', 'medium'] },
        message: { type: 'string' },
        service: { type: 'string' }
      },
      required: ['severity', 'message', 'service']
    }
  }
];

async function runAgent(userMessage: string) {
  const messages: Anthropic.MessageParam[] = [
    { role: 'user', content: userMessage }
  ];

  while (true) {
    const response = await anthropic.messages.create({
      model: 'claude-opus-4-7',
      max_tokens: 4096,
      tools,
      messages
    });

    if (response.stop_reason === 'end_turn') {
      // Agent is done
      const textBlock = response.content.find(b => b.type === 'text');
      return textBlock?.type === 'text' ? textBlock.text : '';
    }

    if (response.stop_reason === 'tool_use') {
      // Execute all tool calls in this response
      const toolResults: Anthropic.MessageParam = {
        role: 'user',
        content: []
      };

      for (const block of response.content) {
        if (block.type === 'tool_use') {
          const result = await executeTool(block.name, block.input);
          (toolResults.content as Anthropic.ToolResultBlockParam[]).push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: JSON.stringify(result)
          });
        }
      }

      messages.push({ role: 'assistant', content: response.content });
      messages.push(toolResults);
    }
  }
}

async function executeTool(name: string, input: Record<string, unknown>) {
  // Dispatch to actual implementations
  switch (name) {
    case 'get_database_stats':
      return getDatabaseStats(input.database_name as string);
    case 'create_alert':
      return createPagerDutyAlert(input as { severity: string; message: string; service: string });
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
}

import { createClient } from 'redis';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

async function cachedLLMCall(query: string): Promise<string> {
  // Generate embedding for the query
  const queryEmbedding = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: query
  });
  const vector = queryEmbedding.data[0].embedding;

  // Check cache for semantically similar query (cosine similarity > 0.95)
  const cacheKey = `llm-cache:${await findSimilarCacheKey(vector, threshold: 0.95)}`;
  const cached = cacheKey ? await redis.get(cacheKey) : null;

  if (cached) {
    return JSON.parse(cached).response;
  }

  // Cache miss — call the LLM
  const response = await anthropic.messages.create({
    model: 'claude-opus-4-7',
    max_tokens: 1024,
    messages: [{ role: 'user', content: query }]
  });

  const responseText = response.content[0].type === 'text'
    ? response.content[0].text
    : '';

  // Store in cache with embedding for future similarity lookups
  await storeInSemanticCache(vector, query, responseText);

  return responseText;
}

// AI Gateway configuration (using LiteLLM as the gateway)
// litellm-config.yaml
model_list:
  - model_name: claude-fast
    litellm_params:
      model: anthropic/claude-haiku-4-5-20251001
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: claude-smart
    litellm_params:
      model: anthropic/claude-opus-4-7
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: gpt-fallback
    litellm_params:
      model: gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

router_settings:
  routing_strategy: latency-based-routing
  fallbacks:
    - claude-smart: [gpt-fallback]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

// Application uses the gateway instead of provider SDKs directly
const response = await fetch(`${process.env.AI_GATEWAY_URL}/chat/completions`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AI_GATEWAY_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'claude-smart',
    messages: [{ role: 'user', content: userMessage }],
    metadata: { userId, sessionId }   // For cost tracking
  })
});

// evals/classify-ticket.eval.ts
const TEST_CASES = [
  {
    input: "I was charged twice this month",
    expectedCategory: "billing",
    minConfidence: 0.9
  },
  {
    input: "The API returns 500 errors on /users endpoint",
    expectedCategory: "technical",
    minConfidence: 0.85
  },
  {
    input: "Can you add dark mode?",
    expectedCategory: "feature-request",
    minConfidence: 0.8
  }
];

async function runEval() {
  let passed = 0;
  const results = [];

  for (const testCase of TEST_CASES) {
    const result = await classifyTicket(testCase.input);
    const correct = result.category === testCase.expectedCategory
      && result.confidence >= testCase.minConfidence;

    results.push({ ...testCase, result, correct });
    if (correct) passed++;
  }

  console.log(`Passed: ${passed}/${TEST_CASES.length}`);
  return results;
}