dspy-auto-signature 0.1.9

About

AutoSignature inspects a prompt, SDK message array, or dataset and generates a complete dspy.Signature subclass. Structured inputs are designed deterministically; anything else gets a single LLM call (dspy.ChainOfThought). No sandbox, no Deno, no iterative loop — one call and you're done.

• Automatic signature design — Infers instructions, inputs, outputs, field descriptions, and types
• Strongly typed outputs — When the LLM designs the signature (mode="cot" or mode="rlm"), structured outputs become real Pydantic BaseModel types with nested models, Literal enums, and validation
• Dataset-aware generation — Profiles DataFrame columns, distributions, and representative rows
• Ready to use — Returns signatures compatible with dspy.Predict, dspy.ChainOfThought, and other DSPy modules
• Exportable — Renders generated signatures as Python source with to_source()

Requires Python 3.12+ and DSPy 3.2+.

(back to top)

Quick Start

Install

Install AutoSignature with uv (recommended):

uv add dspy-auto-signature

Or with pip:

pip install dspy-auto-signature

Basic Usage

import dspy
import dspy_auto_signature as das

das.configure(lm=dspy.LM("openrouter/openai/gpt-oss-120b"))

signature = das.generate(
    "Given an article, produce a concise summary and three key takeaways."
)

print(signature.to_source())

dspy.configure(lm=dspy.LM("openrouter/openai/gpt-oss-120b"))
summarize = dspy.ChainOfThought(signature.to_signature())
result = summarize(article="...")

(back to top)

SDK Message Formats

AutoSignature accepts message arrays from popular LLM SDKs. Pass your existing conversation history directly — no conversion needed.

OpenAI SDK

import dspy
import dspy_auto_signature as das

das.configure(lm=dspy.LM("openrouter/openai/gpt-oss-120b"))

messages = [
    {"role": "system", "content": "You are a technical writer who produces clear documentation."},
    {"role": "user", "content": "Write a README for a Python CLI tool that converts CSV to JSON."},
]

signature = das.generate(messages)
print(signature.to_source())

Anthropic SDK

messages = [
    {"role": "user", "content": "Analyze the sentiment of customer reviews."},
    {"role": "assistant", "content": "I'll classify each review as positive, negative, or neutral."},
]

signature = das.generate(messages)

Google Gemini SDK

contents = [
    {"role": "user", "parts": [{"text": "Extract key entities from this legal contract."}]},
    {"role": "model", "parts": [{"text": "I'll identify parties, dates, and obligations."}]},
]

signature = das.generate(contents)

LiteLLM / OpenAI-Compatible

Any SDK that produces OpenAI-style [{"role": "...", "content": "..."}] arrays works out of the box — including LiteLLM, Azure OpenAI, Ollama, and vLLM.

See examples/sdk.py for a complete runnable example.

DataFrame Example

Install with the pandas extra to get pandas:

uv add "dspy-auto-signature[pandas]"

Or with pip:

pip install "dspy-auto-signature[pandas]"

Datasets are profiled before generation so the signature reflects your column names, types, and representative rows. Add mode="cot" to let an LLM design the signature from the profile instead.

import dspy
import pandas as pd
import dspy_auto_signature as das

das.configure(lm=dspy.LM("openrouter/openai/gpt-oss-120b"))

tickets = pd.DataFrame(
    [
        {"message": "Server is down", "urgency": "high"},
        {"message": "Please update my profile", "urgency": "low"},
        {"message": "Payment failed", "urgency": "high"},
    ]
)

signature = das.generate(
    tickets,
    task_hint="Classify support ticket urgency from the message",
)

print(signature.to_source())

(back to top)

API

generate(source, task_hint=None, *, input_hints=None, output_hints=None)

Generates a dspy.Signature subclass from prompt material or tabular data.

Supported input formats:

• Raw strings (system prompts, task descriptions)
• OpenAI SDK message arrays: [{"role": "system", "content": "..."}, {"role": "user", "content": "..."}]
• Anthropic SDK message arrays: [{"role": "user", "content": "..."}]
• Google Gemini SDK contents: [{"role": "user", "parts": [{"text": "..."}]}]
• LiteLLM / Azure OpenAI / Ollama / vLLM message arrays
• pandas DataFrames, polars DataFrames / LazyFrames
• list[dict], list[dspy.Example], single dspy.Example

Generation modes (mode parameter):

auto is right for almost everything. Pass mode="cot" or mode="rlm" when you want the LLM to design even structured inputs.

Typed outputs with Pydantic models

Whenever ChainOfThought or the RLM architect designs a signature, structured outputs are strongly typed. Instead of a plain str field described as "JSON containing ...", the architect proposes a full Pydantic model schema, and the generated signature uses a real BaseModel class as the output field type:

import dspy
import dspy_auto_signature as das

das.configure(lm=dspy.LM("openai/gpt-4o-mini"))

Signature = das.generate(
    "Extract the customer's contact information from the support ticket: {ticket}",
    mode="cot",
)
contact_field = Signature.output_fields["contact"].annotation
# A generated pydantic model, e.g. ContactRecord(full_name=..., age=..., ...)
print(contact_field.model_json_schema())

Behavior:

• Multi-field and nested outputs become pydantic model schemas with concrete field types (str, int, float, bool, list[str], dict[str, str], Literal, and nested pydantic models). DSPy validates model responses against the generated model at runtime.
• Enumerated outputs become typing.Literal types.
• Simple scalar outputs stay plain (str, int, ...).
• to_source() renders the Pydantic model classes above the signature class, so exported source is self-contained and importable.
• Deterministic paths (mode="fast" and structural auto inputs) keep their existing inferred types.

The generated PydanticModelSchema type is exported for programmatic use with SignatureSpec and FieldSpec.model_schema.

configure(lm=None, dataset_lm=None, sub_lm=None)

Configures the models used during signature generation.

(back to top)

Contributing

Quick workflow:

1. Fork and branch: git checkout -b feature/name
2. Make changes
3. Commit and push
4. Open a Pull Request

(back to top)

License

MIT (as declared in pyproject.toml).