gcsdk

A Git-like conversation SDK for managing chat histories with branching support. Built with Rust (via Neon) for performance.

Overview

gcsdk models chat conversations as a git-like tree structure where each message is a "commit" that can:

• Have a parent message (forming a linked history)
• Belong to a branch
• Snapshot file state at that point in the conversation

This enables features like:

• Branching conversations to explore different paths
• Switching between conversation branches
• Tracking file changes alongside messages

Installation

Installation

npm install gcsdk
# or
bun add gcsdk
# or
pnpm add gcsdk
# or
yarn add gcsdk

Note: The native module is pre-built and included in the package. No Rust installation required!

Troubleshooting

If you encounter an error about the native module not being found, ensure you're using the published version from npm. The native module is pre-built and included in the package.

If you're developing locally, you'll need Rust installed to build the native module:

cd native
npm install
npm run build

From source

git clone https://github.com/warpy-ai/gcsdk.git
cd gcsdk
npm install
npm run build

Usage

import { GitChat } from "gcsdk";

const chat = new GitChat();

// Commit a message with file snapshots
await chat.commit(
  { role: "user", content: "Hello!" },
  { "main.ts": "console.log('hello')" }
);

await chat.commit(
  { role: "assistant", content: "Hi there!" },
  { "main.ts": "console.log('hello')" }
);

// Create a branch from main
chat.createBranch("experiment", "main");
chat.checkout("experiment");

// Commits on this branch won't affect main
await chat.commit(
  { role: "user", content: "Let's try something different" },
  { "main.ts": "console.log('experiment')" }
);

// Switch back to main
chat.checkout("main");

// Get conversation history for current branch
const history = chat.getHistory();

API

GitChat

commit(message, files): Promise<string>

Commits a message to the current branch with an optional file snapshot.

• message: { role: "user" | "assistant" | "system", content: string }
• files: Record<string, string> - filepath to content mapping
• Returns: commit ID (SHA256 hash)

createBranch(branchName, baseBranchName): void

Creates a new branch from an existing branch's head.

checkout(branchName): void

Switches to the specified branch.

getHistory(): ChatNode[]

Returns the full message history for the current branch, ordered from oldest to newest.

ChatNode

interface ChatNode {
  id: string;
  parent_id: string | null;
  role: string;
  content: string;
  vfs_snapshot: Record<string, string>;
}

Architecture

• TypeScript layer (index.ts): Provides the high-level GitChat API
• Rust native module (native/src/lib.rs): Handles the core data structures and operations using Neon bindings

The conversation tree is stored in memory with:

• nodes: HashMap of commit ID to ChatNode
• branches: HashMap of branch name to head commit ID

Development

# Build native module
cd native && npm run build

# Run tests
npm test

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache-2.0