noema v0.0.3

Noema

A TypeScript library for AI-powered React component generation and selection. Built with OpenAI, this library helps you generate React components from natural language descriptions or select from existing component libraries.

Features

• 🤖 AI-Powered: Uses OpenAI's latest models for intelligent component generation and selection
• 🎨 Component Generation: Generate complete React components from text descriptions
• 📚 Component Selection: Intelligently select from your existing component library based on requirements
• 🔒 Type Safe: Built with TypeScript for a great development experience
• ⚛️ React Ready: Designed for React 18+ applications
• 🛠️ Flexible: Use your own OpenAI API key and customize generation parameters

Installation

npm install noema

Requirements

• Node.js >= 20.0.0
• React >= 18.0.0

Quick Start

Setup

First, create a new NoemaAgent with your OpenAI API key:

import { NoemaAgent, OpenAIAIProvider } from 'noema';

// Basic setup (uses gpt-4o by default)
const agent = new NoemaAgent({
  aiProvider: new OpenAIAIProvider('your-openai-api-key')
});

// Advanced setup with custom model and base URL
const advancedAgent = new NoemaAgent({
  aiProvider: new OpenAIAIProvider(
    'your-openai-api-key',
    'gpt-4-turbo-preview',  // optional: specify different model
    'https://your-proxy.com/v1'  // optional: custom base URL for enterprise/proxy setups
  )
});

Generating Components

Generate a new React component from a text description:

const result = await agent.generateComponent(
  "Create a user profile card",
  "The card should display a user's name, avatar, and bio in a modern design"
);

console.log(result.code);
// Returns TypeScript React component code

Selecting Components

Select from your existing component library based on requirements:

const components = [
  {
    name: 'Button',
    component: Button,
    propsSchema: {
      label: 'string',
      variant: ['primary', 'secondary']
    }
  },
  {
    name: 'Card',
    component: Card,
    propsSchema: {
      title: 'string',
      content: 'string'
    }
  }
];

const result = await agent.chooseComponent(
  "I need a clickable element for form submission",
  components
);

// Returns { component: Button, props: { label: 'Submit', variant: 'primary' } }

Generating Full Pages

Generate complete page layouts with multiple components:

const result = await agent.generatePage(
  "Create a dashboard page",
  "The dashboard should include a header with navigation, a main stats section, and a footer"
);

console.log(result.code);
// Returns TypeScript React page component code

Using React Hooks

The library provides React hooks for easier integration:

import { useGeneratedComponent, useGeneratedPage } from 'noema';

function MyComponent() {
  const { generated, loading, error } = useGeneratedComponent(
    agent,
    "dashboard context",
    "Create a stats display component"
  );

  if (loading) return <div>Generating component...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!generated) return null;

  // Use the generated component code
  return <div>{generated.code}</div>;
}

API Reference

NoemaAgent

The main class for interacting with the AI capabilities:

class NoemaAgent {
  constructor(options: NoemaOptions);
  
  async generateComponent(
    context: string,
    requirement: string,
    componentLibrary?: ComponentDefinition[]
  ): Promise<GeneratedComponent>;

  async generatePage(
    context: string,
    requirement: string,
    componentLibrary?: ComponentDefinition[]
  ): Promise<GeneratedPage>;

  async chooseComponent(
    context: string,
    components: ComponentDefinition[]
  ): Promise<ChosenComponent>;
}

OpenAIAIProvider

The default AI provider using OpenAI:

class OpenAIAIProvider implements AIProvider {
  constructor(
    apiKey: string,
    model?: string,  // defaults to "gpt-4o"
    baseURL?: string // optional base URL for enterprise/proxy setups
  );
  
  async generate(
    prompt: string,
    options?: { max_tokens?: number; temperature?: number }
  ): Promise<string>;
}

React Hooks

function useGeneratedComponent(
  agent: NoemaAgent,
  context: string,
  requirement: string,
  componentLibrary?: ComponentDefinition[]
): {
  generated: GeneratedComponent | null;
  loading: boolean;
  error: string | null;
  regenerate: () => void;
};

function useGeneratedPage(
  agent: NoemaAgent,
  context: string,
  requirement: string,
  componentLibrary?: ComponentDefinition[]
): {
  generated: GeneratedPage | null;
  loading: boolean;
  error: string | null;
  regenerate: () => void;
};

License

MIT License - see the LICENSE file for details.