From f3b882ca2f25903071fcc2d024cc90a4d575beea Mon Sep 17 00:00:00 2001 From: Enrico Ros Date: Fri, 14 Mar 2025 23:55:23 -0700 Subject: [PATCH] AIX: update readme --- src/modules/aix/AIX.README.md | 441 +--------------------------------- 1 file changed, 6 insertions(+), 435 deletions(-) diff --git a/src/modules/aix/AIX.README.md b/src/modules/aix/AIX.README.md index 6ff36735e..090305a2e 100644 --- a/src/modules/aix/AIX.README.md +++ b/src/modules/aix/AIX.README.md @@ -179,440 +179,11 @@ sequenceDiagram AIX Client ->> AIX Client: Timeout if no response received within set time ``` -## Structure (This was the initial - being replaced part by part right now - will come back to this later to update) +--- ---- below the line --- +### 2025-03-14 Update +AIX is used in production in Big-AGI and is stable and performant. +The code is tightly coupled with the tRPC framework and the rest of our codebase, +so it is not recommended to use it outside of our ecosystem. -Here's the file structure we'll use: - -1. `types.ts`: Basic types used across the API -2. `blocks.ts`: Input and output block definitions -3. `parameters.ts`: Parameter interfaces for various API calls -4. `foundation-api.ts`: Foundation API interfaces -5. `advanced-api.ts`: Advanced API interfaces -6. `instruction-api.ts`: Instruction API interfaces and types -7. `aix-client.ts`: Main client interface (without implementation) -8. `react-component.tsx`: React component for using the AIX API - -Let's go through each file in detail: - -1. `types.ts` - -```typescript -export interface TokenUsage { - promptTokens: number; - completionTokens: number; - totalTokens: number; -} - -export interface StreamOptions { - onPartialResponse?: (partial: Partial) => void; - signal?: AbortSignal; -} - -export interface ExtractionSchema { - fields: Array<{ - name: string; - type: 'string' | 'number' | 'boolean' | 'date' | 'array' | 'object'; - description?: string; - }>; -} - -export interface MultiModalContext { - text?: string[]; - images?: ImageInputBlock[]; - structuredData?: Record; -} - -export interface PersonaState { - knowledgeGrowth: Record; - adaptationLevel: number; - specializations: string[]; -} -``` - -2. `blocks.ts` - -The code implements these as **AixWire_Parts** - -```typescript -export type InputBlock = InputContentBlock | InputMetaBlock; - -export type InputContentBlock = - | TextInputBlock - | ImageInputBlock - | ToolOutputBlock - | FunctionCallResultBlock - | EmbeddingInputBlock; - -export type InputMetaBlock = - | ContextMetaBlock - | ControlMetaBlock; - -export interface TextInputBlock { - type: 'text'; - content: string; - role: 'user' | 'assistant' | 'function'; -} - -export interface ImageInputBlock { - type: 'image'; - content: string; - mimeType: string; -} - -export interface ToolOutputBlock { - type: 'tool_output'; - toolName: string; - content: any; -} - -export interface FunctionCallResultBlock { - type: 'function_call_result'; - name: string; - content: any; -} - -export interface EmbeddingInputBlock { - type: 'embedding'; - content: number[]; -} - -export interface ContextMetaBlock { - type: 'context'; - contextType: string; - content: any; -} - -export interface ControlMetaBlock { - type: 'control'; - instruction: string; -} - -export type OutputBlock = OutputContentBlock | OutputMetaBlock; - -export type OutputContentBlock = - | TextOutputBlock - | ImageOutputBlock - | ToolCallOutputBlock - | FunctionCallOutputBlock; - -export type OutputMetaBlock = - | ErrorOutputBlock - | CompletionStatusBlock - | ConfidenceBlock; - -export interface TextOutputBlock { - type: 'text'; - content: string; - role: 'assistant' | 'system'; -} - -export interface ImageOutputBlock { - type: 'image'; - url: string; - mimeType: string; -} - -export interface ToolCallOutputBlock { - type: 'tool_call'; - toolName: string; - arguments: Record; -} - -export interface FunctionCallOutputBlock { - type: 'function_call'; - name: string; - arguments: string; -} - -export interface ErrorOutputBlock { - type: 'error'; - code: string; - message: string; -} - -export interface CompletionStatusBlock { - type: 'completion_status'; - status: 'complete' | 'incomplete' | 'truncated'; -} - -export interface ConfidenceBlock { - type: 'confidence'; - score: number; -} -``` - -3. `parameters.ts` - -```typescript -export interface BaseParameters { - model?: string; - temperature?: number; - maxTokens?: number; -} - -export interface GenerationParameters extends BaseParameters { - // Additional generation-specific parameters -} - -export interface ExtractionParameters extends BaseParameters { - // Additional extraction-specific parameters -} - -export interface ImageManipulationParameters extends BaseParameters { - dimensions?: { width: number; height: number }; - style?: string; -} - -export interface ReasoningParameters extends BaseParameters { - depthOfAnalysis?: 'shallow' | 'moderate' | 'deep'; -} - -export interface PersonaParameters extends BaseParameters { - personaId: string; -} -``` - -4. `foundation-api.ts` - -```typescript -import { InputBlock, OutputBlock } from './blocks'; -import { GenerationParameters, ExtractionParameters, ImageManipulationParameters } from './parameters'; -import { TokenUsage, StreamOptions, ExtractionSchema } from './types'; - -export interface GenerationRequest { - inputSequence: InputBlock[]; - parameters: GenerationParameters; -} - -export interface GenerationResponse { - outputSequence: OutputBlock[]; - usage: TokenUsage; -} - -export interface ExtractionRequest { - data: string | Blob; - schema: ExtractionSchema; - parameters: ExtractionParameters; -} - -export interface ExtractedInformation { - [key: string]: any; -} - -export interface ImageManipulationRequest { - operation: 'generate' | 'edit' | 'variation'; - prompt?: string; - baseImage?: ImageInputBlock; - parameters: ImageManipulationParameters; -} - -export interface ImageManipulationResult { - images: ImageOutputBlock[]; - metadata: Record; -} - -export interface FoundationAPIs { - generateContent( - request: GenerationRequest, - options?: StreamOptions - ): Promise; - - extractInformation( - request: ExtractionRequest, - options?: StreamOptions - ): Promise; - - imageManipulation( - request: ImageManipulationRequest, - options?: StreamOptions - ): Promise; -} -``` - -5. `advanced-api.ts` - -```typescript -import { InputBlock, OutputBlock } from './blocks'; -import { ReasoningParameters, PersonaParameters } from './parameters'; -import { MultiModalContext, PersonaState, StreamOptions } from './types'; - -export interface MultiModalReasoningRequest { - context: MultiModalContext; - query: string; - parameters: ReasoningParameters; -} - -export interface ReasoningResult { - conclusion: string; - confidenceScore: number; - supportingEvidence: any[]; -} - -export interface PersonaInteractionRequest { - input: InputBlock[]; - parameters: PersonaParameters; -} - -export interface PersonaResponse { - output: OutputBlock[]; - personaState: PersonaState; -} - -export interface AdvancedAPIs { - multiModalReasoning( - request: MultiModalReasoningRequest, - options?: StreamOptions - ): Promise; - - adaptivePersona( - request: PersonaInteractionRequest, - options?: StreamOptions - ): Promise; -} -``` - -6. `instruction-api.ts` - -```typescript -export interface Instruction { - id: string; - type: string; - parameters: Record; - condition?: (context: ExecutionContext) => boolean; - userInteraction?: UserInteractionConfig; - subInstructions?: Instruction[]; -} - -export interface UserInteractionConfig { - componentType: string; - props: Record; -} - -export interface InstructionResult { - id: string; - type: string; - status: 'completed' | 'awaiting_user_input' | 'cancelled' | 'error'; - output?: any; - error?: string; - userInteraction?: UserInteractionConfig; -} - -export interface ExecutionContext { - variables: Record; - results: InstructionResult[]; -} - -export interface ExecuteInstructionsOptions { - initialContext?: Partial; - onUserInteractionRequired: (interaction: UserInteractionConfig) => Promise; - onProgress?: (result: InstructionResult) => void; - onCancel?: () => void; - signal?: AbortSignal; -} - -export interface UserInteractionResult { - status: 'completed' | 'cancelled'; - data?: any; -} -``` - -7. `aix-client.ts` - -```typescript -import { FoundationAPIs } from './foundation-api'; -import { AdvancedAPIs } from './advanced-api'; -import { Instruction, InstructionResult, ExecuteInstructionsOptions } from './instruction-api'; - -export interface AIXClient { - foundation: FoundationAPIs; - advanced: AdvancedAPIs; - - executeInstructions( - instructions: Instruction[], - options?: ExecuteInstructionsOptions - ): AsyncIterableIterator; -} -``` - -8. `react-component.tsx` - -```tsx -import React, { useState, useCallback, useEffect } from 'react'; -import { AIXClient } from './aix-client'; -import { Instruction, InstructionResult, UserInteractionConfig } from './instruction-api'; - -const DynamicComponent = React.lazy(() => import('./DynamicComponent')); - -interface AIXWorkflowProps { - client: AIXClient; - initialInstructions: Instruction[]; -} - -export const AIXWorkflow: React.FC = ({ client, initialInstructions }) => { - const [results, setResults] = useState([]); - const [currentInteraction, setCurrentInteraction] = useState(null); - - const handleUserInteraction = useCallback(async (interaction: UserInteractionConfig) => { - return new Promise<{ status: 'completed' | 'cancelled'; data?: any }>((resolve) => { - setCurrentInteraction({ ...interaction, onComplete: resolve }); - }); - }, []); - - const runWorkflow = useCallback(async () => { - const abortController = new AbortController(); - - for await (const result of client.executeInstructions(initialInstructions, { - onUserInteractionRequired: handleUserInteraction, - signal: abortController.signal, - })) { - setResults(prev => [...prev, result]); - } - - return () => abortController.abort(); - }, [client, initialInstructions, handleUserInteraction]); - - useEffect(() => { - const cleanup = runWorkflow(); - return cleanup; - }, [runWorkflow]); - - const handleInteractionComplete = useCallback((data: any) => { - currentInteraction?.onComplete({ status: 'completed', data }); - setCurrentInteraction(null); - }, [currentInteraction]); - - const handleInteractionCancel = useCallback(() => { - currentInteraction?.onComplete({ status: 'cancelled' }); - setCurrentInteraction(null); - }, [currentInteraction]); - - return ( -
- {results.map((result) => ( -
-

{result.type}

- 
{JSON.stringify(result.output, null, 2)}
-
- ))} - {currentInteraction && ( - Loading...
}> - - - )} - - ); -}; -``` - -This file structure provides a clean separation of concerns, with each file focusing on a specific aspect of the AIX API. The `types.ts`, `blocks.ts`, and `parameters.ts` files contain the fundamental building blocks used throughout the API. The `foundation-api.ts` and `advanced-api.ts` files define the core AI functionalities, while `instruction-api.ts` provides the high-level instruction execution system. The `aix-client.ts` file defines the main client interface, and `react-component.tsx` offers a ready-to-use React component for integrating the AIX API into a React application. - -This structure allows for easy maintenance, extensibility, and clarity in the API design, making it easier for developers to understand and use the AIX system in their applications. \ No newline at end of file +For a great Typescript alternative we recommend the Vercel AI SDK.