DSJS: Programming (not prompting) Foundation Models in JavaScript/TypeScript

DSJS is a JavaScript/TypeScript port of DSPy, a framework for programming foundation models (LLMs) with higher-level abstractions than just prompting.

🌟 Features

• Declarative Programming Model: Define inputs and outputs with signatures, not prompts
• Multi-Provider Support: Use OpenAI, Anthropic, or OpenRouter with the same code
• Advanced Reasoning: Chain-of-Thought, ReAct agents, and more
• Retrieval-Augmented Generation: Connect to various vector databases
• Instruction Optimization: Automatically improve prompts with MIPRO and Bootstrap
• TypeScript-First: Full type safety and excellent developer experience

🚀 Quick Start

Setup

1. Clone the Repository:

   git clone https://github.com/laz1mov/dsjs
   cd dsjs

2. Install Dependencies: Make sure you have Node.js and npm installed. Then, run the following command in the root directory of the project:

   npm install

   This installs all necessary libraries defined in package.json.

3. Configure Environment Variables: Create a file named .env in the root directory. Copy the contents of .env.example or add the necessary API keys for the LLM providers you plan to use. For example:

   # Required for most examples using OpenRouter
   OPENROUTER_API_KEY=your_openrouter_api_key_here
   
   # Optional, for specific examples or direct usage
   # OPENAI_API_KEY=your_openai_api_key
   # ANTHROPIC_API_KEY=your_anthropic_api_key
   
   # Add other credentials if needed (e.g., for Neo4j, Supabase examples)
   # NEO4J_URI=...
   # SUPABASE_URL=...

   Note: You only need to add keys for the services you intend to test.

4. Build the Project: DSJS uses TypeScript. You need to compile the source code into JavaScript before running the examples. Run the build command:

   npm run build

   This command compiles the code from the src/ directory into the dist/ directory, which the examples import from.

Running Examples

Once the setup is complete, you can run the examples using Node.js from the root directory.

1. Basic Example (examples/basic.js)

• What it does: Demonstrates the most fundamental usage of DSJS: defining a simple signature (QuestionAnswerSignature), configuring an LLM (using OpenRouter with Claude Haiku by default in the example), creating a Predict module, and asking it a question.
• Prerequisites: Requires OPENROUTER_API_KEY in your .env file. Ensure your key has access to the model specified in the script (currently anthropic/claude-3.5-haiku).
• Command:

  node examples/basic.js

• Expected Output: The script will print the question and the answer generated by the configured LLM. It also includes debugging logs showing the raw result object.

2. Assertions Example (examples/assertions.js)

• What it does: Shows how to use DSJS Assertions (LengthAssertion, ContentAssertion, FormatAssertion) to constrain and validate the output of an LLM. It generates product descriptions with and without various constraints using OpenRouter with Claude Haiku.
• Prerequisites: Requires OPENROUTER_API_KEY in your .env file. Ensure your key has access to the model specified in the script (currently anthropic/claude-3.5-haiku).
• Command:

  node examples/assertions.js

• Expected Output: The script will print several product descriptions, showing the output from generators with different assertions applied. It includes checks to verify if the assertions were met (e.g., word count, content inclusion/exclusion, format). You might see warnings about JSON parsing if the LLM returns plain text, which is handled by the example.

3. Chain of Thought Example (examples/openrouter-chain-of-thought.js)

• What it does: Demonstrates the ChainOfThought module for solving problems that require step-by-step reasoning. It uses custom internal signatures (ReasoningOnlySignature, AnswerFromReasoningSignature) to guide the LLM more explicitly. It uses OpenRouter with Claude Opus by default.
• Prerequisites: Requires OPENROUTER_API_KEY in your .env file. The example uses a powerful model like Claude Opus (anthropic/claude-3-opus-20240229) by default, which might require paid credits on OpenRouter. Ensure your key has access.
• Command:

  node examples/openrouter-chain-of-thought.js

• Expected Output: For each math problem, the script will print the step-by-step reasoning generated by the LLM, followed by the final numerical solution. Debug logs show the full result object. You might see warnings about JSON parsing if the LLM returns plain text for intermediate steps, which is handled by the example.

Other Examples:

Explore the examples/ directory for more advanced use cases, including ReAct agents, RAG with different databases, and instruction optimization. Refer to the specific example files or corresponding documentation in the docs/ folder for details on running them.

📚 Documentation

For more detailed documentation, examples, and guides, please visit:

• Getting Started Guide
• API Reference
• Examples
• Concepts and Architecture

🔧 Multi-Provider Support

DSJS supports multiple LLM providers:

OpenAI

const lm = new ds.OpenAILM({
  model: 'gpt-4',
  temperature: 0.2,
  maxTokens: 1000
});

Anthropic

const lm = new ds.AnthropicLM({
  model: 'claude-3-opus-20240229',
  temperature: 0.2,
  maxTokens: 1000
});

OpenRouter (access to multiple models)

const lm = new ds.OpenRouterLM({
  model: 'anthropic/claude-3-opus-20240229',
  temperature: 0.0,
  maxTokens: 500
});

🧩 Key Components

• Signatures: Define inputs and outputs for your modules
• Predict: Basic prediction module
• ChainOfThought: Step-by-step reasoning
• ReAct: Reasoning and acting with tools
• Retrieve: Retrieval-augmented generation
• Teleprompt: Instruction optimization (MIPRO, Bootstrap)

🛣️ Roadmap

See our detailed roadmap in implementation-roadmap.md.

Our key focus areas are:

1. Comprehensive Testing
2. Complete Documentation & Practical Examples
3. Enhanced Developer Experience (DX)
4. Robust Development Practices (CI/CD, Contributions)
5. Performance Optimization
6. Full Parity with DSPy & JS/TS Extensions

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for more details.

📄 License

DSJS is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Stanford NLP Group for creating the original DSPy
• All contributors to this project