Skip to content

rfc: Celeste JS/TS - A Framework-Agnostic "Twin" Library #149

Description

@Alistorm

Context

Celeste currently fills a critical gap in the Python ecosystem: "Primitives, not Frameworks." It offers a clean, provider-agnostic way to handle Multi-Modal I/O without the bloat of LangChain or the vendor lock-in of official SDKs.

However, the JavaScript/TypeScript ecosystem faces the exact same problem, but worse:

  1. Vercel AI SDK: Excellent, but heavily coupled to Next.js patterns and React streams. Not ideal for backend Node/Bun/Deno workers.
  2. LangChain.js: Extremely heavy, complex abstractions ("Chains", "Agents") that obscure the underlying API calls.
  3. Vendor SDKs: Disparate interfaces (OpenAI vs Anthropic vs Google), forcing developers to write wrapper code.

The Proposal

I propose creating @withceleste/core, a TypeScript "Twin" of the Python library.

The goal is API Symmetry: A developer should be able to move between Python and TypeScript and see the exact same primitives, concepts, and method signatures.

Architectural Blueprint

We can map the successful Python architecture 1:1 to modern TypeScript standards.

Concept Python Implementation TypeScript Implementation
Validation Pydantic (BaseModel) Zod (Standard, runtime validation)
Transport httpx.AsyncClient Native fetch (Edge/Worker compatible)
Streaming AsyncIterator AsyncGenerator (for await...)
Configuration class TextParameters interface TextParameters
Discovery Provider Enums const Provider Objects (Tree-shakeable)

Proposed API Surface

import { Celeste, Modality } from '@withceleste/core';
import { z } from 'zod';

// 1. Unified Client
const client = new Celeste({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY
});

// 2. Structured Generation (Symmetric to Python)
const response = await client.text.generate({
  model: 'gpt-4o',
  prompt: 'Extract user info',
  // Direct Zod support mirrors Pydantic support
  outputSchema: z.object({
    name: z.string(),
    age: z.number()
  })
});

// 3. Streaming (Standard Async Iterator)
const stream = await client.text.stream.generate({
  model: 'claude-3-5-sonnet',
  prompt: 'Write a poem'
});

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

Strategic Value

  1. Full-Stack Consistency: Teams (like mine at Upfund) often have Python ETL pipelines and Node.js API Gateways. Sharing the exact same mental model for AI calls across both is a massive productivity booster.
  2. Edge Compatibility: By using native fetch and avoiding Node-specific libs, this library would work natively in Cloudflare Workers, Supabase Edge Functions, and Deno.
  3. Governance: The same Provider / Model registry logic can be shared (or ported) to ensure capabilities match across languages.

Roadmap

I am willing to scaffold the initial repository structure (monorepo or separate repo) and port the core TextClient logic to demonstrate the symmetry.

  • Define Project Structure (tsc/tsup for bundling).
  • Port TextClient and OpenAI Provider.
  • Implement Zod Schema -> JSON Schema mapper (mirroring structured_outputs.py).

Is the team open to expanding Celeste into a multi-language organization?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions