AI Integration

Technical reference for AI-powered content generation.

Overview

The platform provides AI content generation to help agents create website content (hero text, value propositions, about sections) without manual copywriting. AI is globally configurable with per-workspace feature gating.

Current status: Foundation, Compliance, Website Blocks, and Automations (social posts + email drafts) complete.

Package Structure

packages/ai/
├── src/
│   ├── index.ts              # Public exports
│   ├── types.ts              # AI-specific types
│   ├── usage.ts              # Track and check limits
│   ├── providers/
│   │   ├── index.ts          # Provider interface & factory
│   │   ├── anthropic.ts      # Claude implementation
│   │   └── openai.ts         # GPT-4 implementation
│   ├── prompts/
│   │   ├── index.ts          # Prompt exports
│   │   └── website-blocks.ts # Value props, hero, about
│   ├── automations/
│   │   ├── index.ts              # Automation exports
│   │   ├── persona.ts            # Agent persona context
│   │   ├── prompt-builder.ts     # Prompt composition + luxury vocabulary
│   │   ├── social-post-generator.ts  # Social caption generation
│   │   └── email-draft-generator.ts  # Email marketing generation
│   └── safeguards/
│       ├── index.ts          # Safeguard exports
│       ├── fair-housing.ts   # Prohibited term detection
│       ├── pii-filter.ts     # Strip PII before AI
│       └── audit.ts          # Audit logging
├── package.json
└── tsconfig.json

Provider Abstraction

The AI package supports multiple providers through a common interface:

import { createProvider, generateWebsiteBlocks } from '@1oak/ai';

const provider = createProvider({
  provider: 'anthropic',   // or 'openai'
  apiKey: decryptedApiKey,
  model: 'claude-sonnet-4',
});

const result = await generateWebsiteBlocks(provider, {
  agentName: 'Jane Smith',
  brokerage: 'Luxury Homes Realty',
  serviceAreas: ['Miami Beach', 'Coral Gables'],
  specialty: 'luxury waterfront properties',
});

Model Recommendations

Fair Housing Safeguards

Every AI generation passes through three layers of compliance:

1. System Prompt Enforcement

All prompts include explicit Fair Housing Act instructions. The AI is instructed to never reference protected classes or use coded discriminatory language.

2. Post-Generation Filtering

Generated content is scanned for prohibited patterns:

• Race/ethnicity references
• Religious institution proximity ("near church/synagogue")
• Familial status language ("no children," "adult community")
• Coded language ("safe neighborhood," "good schools," "family-friendly")

3. Mandatory Human Review

No AI-generated content is published automatically. The flow is:

Generate → Fair Housing check → Human review → Approve/Edit → Publish

If the Fair Housing check flags terms, the content is still presented to the agent with warnings, but cannot be published without review.

Configuration

Global Settings

Platform-wide AI configuration is managed by platform admins:

interface AIGlobalSettings {
  enabled: boolean;                    // Master kill switch
  defaultProvider: 'anthropic' | 'openai';
  defaultModel: AIModel;
  premiumModel: AIModel;
  usageAlertThreshold?: number;        // Alert at X% of monthly budget
  monthlyBudgetCents?: number;
}

Workspace Settings

Per-workspace feature gating:

interface WorkspaceFeatures {
  aiContentGeneration?: boolean;       // Enable AI features
  aiTier?: 'free' | 'pro' | 'enterprise';
}

Tier Limits

Database Tables

ai_usage

Tracks token usage and costs per workspace. See Database Schema for full column definitions.

ai_content_audit

Audit trail for all generated content, including Fair Housing check results, flagged terms, and approval status. Required for compliance review.

API Routes

See API Reference for request/response details.

MLS Data Rules

• NEVER replace original MLS PublicRemarks — keep in separate public_remarks field
• AI content stored in marketing_description field
• Require agent review/approval before publishing
• NEVER submit AI-enhanced descriptions back to the MLS

Audit Trail

Every AI generation creates an ai_content_audit record with:

• The raw generated content
• Fair Housing check pass/fail status
• Any flagged terms
• Review status (pending/approved/rejected)
• Reviewer identity and timestamp

This ensures a complete compliance trail for legal review.

Automations Integration

The Automations system extends AI content generation with configurable rules and a persona-aware prompt pipeline. Automations use the same provider abstraction, Fair Housing safeguards, usage tracking, and audit trail as website block generation.

Key additions:

• Persona prompt builder (packages/ai/src/automations/persona.ts)
• Automation-specific prompt composition with luxury price tier guidance (packages/ai/src/automations/prompt-builder.ts)
• Social post generator with PII stripping (packages/ai/src/automations/social-post-generator.ts)
• Email draft generator for marketing emails (packages/ai/src/automations/email-draft-generator.ts)
• automation_social_post and automation_email_draft operation types for usage tracking

See Automations Reference for full architecture details.

Related Documentation

• Database Schema — AI table definitions
• API Reference — AI endpoint specifications
• Security — RLS and token encryption
• Automations Reference — Automations architecture and API