Contributing

Refrase is open source and we welcome contributions, especially new model adapters. Here is how to add support for a new model.

Adding a New Model Adapter

Follow these five steps to add optimization rules for a new model.

1

Create the adapter file

Add a new file in src/adapters/ following the naming convention <provider>-<model>.ts. Export a default adapter object that implements the ModelAdapter interface.

// src/adapters/example-model.ts
import { ModelAdapter } from "../types";

const adapter: ModelAdapter = {
  id: "example-model-v1",
  name: "Example Model v1",
  provider: "example",
  capabilities: ["structured_output"],
  rules: [
    {
      id: "explicit-format",
      description: "Add explicit output format instructions",
      priority: 1,
      apply: (prompt) => {
        // transformation logic
        return prompt;
      },
    },
  ],
};

export default adapter;
2

Register the adapter

Import your adapter in src/adapters/index.ts and add it to the registry. The adapter will be automatically available via the SDK and API.

3

Write tests

Create a test file at tests/adapters/<provider>-<model>.test.ts. Each rule should have at least one test verifying the transformation. Use snapshot tests for full prompt before/after comparisons.

4

Implement the Python adapter

Refrase maintains parity between the TypeScript and Python SDKs. Add the equivalent adapter in python/refrase/adapters/<provider>_<model>.py with matching rules and behavior. Run the Python test suite to confirm parity.

5

Submit a pull request

Open a PR against the main branch. Include a brief description of the model's optimization preferences and link to any relevant documentation from the model provider. CI will run both TypeScript and Python test suites.

Testing Requirements

  • All adapter rules must have unit tests in both TypeScript and Python
  • Snapshot tests must cover at least three prompt types: short, medium, and long
  • CI must pass before merging (both test suites, linting, and type checking)
  • New models should be added to the benchmark suite for ongoing regression testing

Issues and Discussions

Found a bug or have an idea? Open an issue on GitHub Issues. For broader questions or feature discussions, use GitHub Discussions.