docs: updating readme and adding examples readme (#135)

Updates the readme with feedback from #129 Also adds an examples README
gensx-inc · Jan 18, 2025 · 9585929 · 9585929
1 parent f2bf1c7
commit 9585929
Show file tree

Hide file tree

Showing 2 changed files with 157 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -1,42 +1,141 @@
-# GenSX Monorepo
+# GenSX ⚡️
 
-This monorepo contains GenSX and its related packages - a framework for building LLM workflows and AI agents with JSX on the backend. Every GenSX component is a pure function, making it easily shareable by default.
+[![npm version](https://badge.fury.io/js/gensx.svg)](https://badge.fury.io/js/gensx)
+[![Website](https://img.shields.io/badge/Visit-gensx.dev-orange)](https://gensx.dev)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Repository Structure
+[GenSX](https://gensx.dev/) is a simple typescript framework for building complex LLM applications. It's built around functional, reusable components that are composed to create and orchestrate workflows.
 
-- `packages/` - Published packages
-- `examples/` - Example applications and use cases
-- `docs` - `https://gensx.dev` Documentation
+Designed for backend development, GenSX makes it easy to build and test powerful LLM workflows that can be turned into REST APIs or integrated into existing applications.
 
-## Prerequisites
+## Why GenSX?
 
-- Node.js (LTS version recommended)
-- pnpm (v9.12.2 or later)
+- 🎯 **Pure Functions**: Components are pure TypeScript functions that are easily testable, reusable, and sharable
+- 🌴 **Natural Composition**: Chain LLM calls using JSX - a familiar, visual syntax that reads top-to-bottom like normal code
+- ⚡️ **Parallel by Default**: Components execute in parallel when possible while maintaining dependencies
+- 🔒 **Type-safe**: Full TypeScript support with no DSLs or special syntax - just standard language features
+- 🌊 **Streaming Built-in**: Stream responses with a single prop change, no refactoring needed
+- 🚀 **Built for Scale**: Start simple and evolve to complex patterns like agents and reflection without changing your programming model
 
-## Documentation
-
-For detailed documentation about GenSX, please refer check out the [docs](https://gensx.dev).
+Check out the [documentation](https://gensx.dev/overview) to learn more about building LLM applications with GenSX.
 
 ## Getting Started
 
-1. Install dependencies:
+To create a new GenSX project, run the following command:
 
 ```bash
-pnpm install
+npm create gensx@latest my-app
 ```
 
-2. Build all packages:
+To add GenSX to an existing project, run the following command and follow the instructions described [here](https://www.npmjs.com/package/gensx):
 
 ```bash
-pnpm build:all
+npm install gensx @gensx/openai
 ```
 
-## Run an example
+Check out the [Quickstart Guide](https://gensx.dev/quickstart) for more details on getting started.
+
+## Building a workflow, the declarative way!
+
+Most LLM frameworks are graph oriented--you express your workflow with nodes, edges, and a global state object. GenSX takes a different approach--you compose your workflow with components, and GenSX handles the execution for you.
+
+You start by defining your components:
+
+```tsx
+import { gsx } from "gensx";
+import { OpenAIProvider, ChatCompletion } from "@gensx/openai";
+
+// Define the input props and output type for type safety
+interface CreateOutlineProps {
+  prompt: string;
+}
+type CreateOutlineOutput = string;
+
+// Create a reusable component that can be composed with others
+const CreateOutline = gsx.Component<CreateOutlineProps, CreateOutlineOutput>(
+  "CreateOutline",
+  async ({ prompt }) => {
+    return (
+      <ChatCompletion
+        model="gpt-4o-mini"
+        messages={[
+          {
+            role: "user",
+            content: `Create an outline for an article about ${prompt}`,
+          },
+        ]}
+      />
+    );
+  },
+);
+
+interface WriteArticleProps {
+  outline: string;
+}
+type WriteArticleOutput = string;
+
+const WriteArticle = gsx.Component<WriteArticleProps, WriteArticleOutput>(
+  "WriteArticle",
+  async ({ outline }) => {
+    return (
+      <ChatCompletion
+        model="gpt-4o-mini"
+        messages={[
+          {
+            role: "user",
+            content: `Use this outline to write a detailed article: ${outline}`,
+          },
+        ]}
+      />
+    );
+  },
+);
+```
 
-```bash
-OPENAI_API_KEY=<my api key> turbo run run --filter="./examples/blogWriter"
+Then you can compose your components together to create a workflow:
+
+```tsx
+// Execute the workflow with the OpenAI provider
+const result = await gsx.execute<string>(
+  <OpenAIProvider apiKey={process.env.OPENAI_API_KEY}>
+    <CreateOutline prompt="the future of LLM dev tools">
+      {(outline) => <WriteArticle outline={outline} />}
+    </CreateOutline>
+  </OpenAIProvider>,
+);
+
+console.log(result);
 ```
 
+## Examples
+
+This repo contains a number of [examples](./examples) to help you get up and running with GenSX.
+
+### Basic Examples
+
+| Example                                      | Description                                               |
+| -------------------------------------------- | --------------------------------------------------------- |
+| 📊 [Structured Outputs](./structuredOutputs) | Demonstrates using structured outputs with GenSX          |
+| 🔄 [Reflection](./reflection)                | Shows how to use a self-reflection pattern with GenSX     |
+| 🌊 [Streaming](./streaming)                  | Demonstrates how to handle streaming responses with GenSX |
+
+### Full Examples
+
+| Example                                         | Description                                                                                  |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| 🔍 [Hacker News Analyzer](./hackerNewsAnalyzer) | Analyzes HN posts and generates summaries and trends using Paul Graham's writing style       |
+| ✍️ [Blog Writer](./blogWriter)                  | Generates blogs through an end-to-end workflow including topic research and content creation |
+
+## Working with this repo
+
+This monorepo contains GenSX, its related packages, examples, and documentation. You can find more detailed instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+### Repository Structure
+
+- `packages/` - Published packages
+- `examples/` - Example applications and use cases
+- `docs` - `https://gensx.dev` Documentation
+
 ## License
 
-Apache 2.0
+[Apache 2.0](./LICENSE)
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,38 @@
+# GenSX Examples 📚
+
+This folder contains a number of different examples to help you get up and running with GenSX.
+
+## Running the Examples
+
+To run the examples, start by installing and building everything from the root directory of the repo. This will install the dependencies and build all of the packages and examples
+
+```bash
+pnpm install
+
+pnpm build:all
+```
+
+From there, follow the instructions in the README of the example you want to run.
+
+Alternatively, you can run the examples directly from the root directory of the repo using the following command:
+
+```bash
+OPENAI_API_KEY=<my api key> turbo run run --filter="./examples/blogWriter"
+```
+
+Make sure to check what environment variables are required for each example.
+
+## Basic Examples
+
+| Example                                      | Description                                               |
+| -------------------------------------------- | --------------------------------------------------------- |
+| 📊 [Structured Outputs](./structuredOutputs) | Demonstrates using structured outputs with GenSX          |
+| 🔄 [Reflection](./reflection)                | Shows how to use a self-reflection pattern with GenSX     |
+| 🌊 [Streaming](./streaming)                  | Demonstrates how to handle streaming responses with GenSX |
+
+## Full Examples
+
+| Example                                         | Description                                                                                  |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| 🔍 [Hacker News Analyzer](./hackerNewsAnalyzer) | Analyzes HN posts and generates summaries and trends using Paul Graham's writing style       |
+| ✍️ [Blog Writer](./blogWriter)                  | Generates blogs through an end-to-end workflow including topic research and content creation |