Skip to main content

Definitions Guide

This guide explains how to construct definitions for ObjectWeaver. A definition describes the structure and instructions for generating objects, arrays, and other data types using LLMs.

Core Concept​

Regardless of the programming language you're using, definitions follow a consistent JSON-based structure with these key components:

  • Type: Specifies the data type (Object, Array, String, Number, Integer, Boolean, Null, Map, Vector)
  • Instruction: Provides clear guidance for what to generate
  • Properties: Describes the fields of an object (when type is Object)
  • Items: Specifies the schema for array elements (when type is Array)

Definition Structure​

Below is the complete Definition structure with all available fields:

Core Fields​

  • type (string): The data type of the schema (e.g., "object", "array", "string", "number", "integer", "boolean", "null", "map", "vector)
  • instruction (string): The instruction for what to generate
  • properties (object): Describes the properties of an object if the schema type is "object"
  • items (Definition): Specifies the schema of items in an array, if the schema type is "array"

Model Configuration​

  • model (string): The model name matching the exact name used by the AI service provider (e.g., OpenAI, Google Gemini)
  • modelConfig (object): Advanced model configuration with the following options:
    • maxCompletionTokens (integer): Upper bound for tokens in completion, including output and reasoning tokens
    • temperature (float): Controls randomness in generation (0.0 to 2.0)
    • topP (float): Nucleus sampling parameter
    • n (integer): Number of completions to generate
    • stream (boolean): Enable streaming responses
    • stop (array of strings): Sequences where generation should stop
    • presencePenalty (float): Penalty for token presence
    • frequencyPenalty (float): Penalty for token frequency
    • seed (integer): Random seed for deterministic output
    • logitBias (object): Token ID bias adjustments
    • logProbs (boolean): Return log probabilities
    • topLogProbs (integer): Number of most likely tokens to return (0-5)
    • user (string): User identifier
    • store (boolean): Store output for distillations and evals
    • reasoningEffort (string): Controls reasoning effort ("low", "medium", "high")
    • metadata (object): Additional metadata to store
    • chatTemplateKwargs (object): Additional template renderer parameters

Processing Control​

  • processingOrder (array of strings): Order of parent property keys that must be processed before this field
  • systemPrompt (string): Custom system prompt for processing at the properties level
  • stream (boolean): Enable streaming for this field
  • overridePrompt (string): Override the default prompt
  • priority (integer): Request priority level
    • 2 - Urgent (highest priority)
    • 1 - Standard priority
    • 0 - Low priority
    • -1 - Eventual (batch processing)

Quality and Evaluation​

  • scoringCriteria (object): Defines how to evaluate quality of generation

    • dimensions (object): Map of score names to evaluation definitions
      • description (string): How to evaluate this dimension
      • scale (object): Numeric range (min/max)
      • type (string): Score type ("numeric", "boolean", "categorical")
      • weight (float): Weight for aggregation (0.0-1.0)
    • evaluationModel (string): Model to use for scoring
    • aggregationMethod (string): How to combine scores ("weighted_average", "minimum", "maximum", "custom")

  • decisionPoint (object): Enable conditional branching based on scores or values

    • name (string): Identifier for debugging
    • evaluationPrompt (string): Guides LLM in scoring
    • branches (array): Conditional paths evaluated in order
      • name (string): Branch identifier
      • conditions (array): ALL must be true (AND logic)
        • field (string): Score or value name to check
        • operator (string): Comparison ("eq", "neq", "gt", "lt", "gte", "lte", "in", "nin", "contains")
        • value (any): Value to compare against
        • fieldPath (string): Full path for nested field access
      • logic (Definition): Evaluation logic
      • then (Definition): Definition to generate if conditions match
      • priority (integer): Branch evaluation order
    • strategy (string): Evaluation strategy ("score", "field", "hybrid")

  • recursiveLoop (object): Enable iterative refinement

    • maxIterations (integer): Maximum generation attempts
    • selection (string): Which iteration to keep ("highest", "lowest", "latest", "first", "all")
    • terminationPoint (DecisionPoint): Stop early if conditions match
    • feedbackPrompt (string): Guides improvement between iterations
    • includePreviousAttempts (boolean): Show LLM previous iterations

  • epistemic (object): Epistemic validation for information validity

    • active (boolean): Whether validation is enabled
    • judges (integer): Number of judges to validate

Data Management​

  • hashMap (object): Create and return a map of values

    • keyInstruction (string): Instruction for generating map keys
    • fieldDefinition (Definition): Definition for map values

  • selectFields (array of strings): Select multiple pieces of information using absolute path notation

    • Examples: "car.color" (single field), "cars.color" (all colors from array)

  • narrowFocus (object): Send focused request with minimal context

    • prompt (string): The prompt sent to the LLM
    • fields (array of strings): Properties to extract and their order
    • keepOriginal (boolean): Keep original prompt for list contexts

External Integration​

  • req (object): Send request to extract information from external databases
    • url (string): Endpoint URL
    • method (string): HTTP method
    • headers (object): Request headers
    • body (object): Request body
    • authorization (string): Authorization token
    • requireFields (array of strings): Required fields

Media Processing​

  • textToSpeech (object): Text-to-speech configuration (use type "byte")

    • model (string): TTS model to use
    • stringToAudio (string): Text content to convert
    • voice (string): Voice for synthesis
    • format (string): Audio format (e.g., mp3, wav)

  • speechToText (object): Speech-to-text configuration

    • model (string): STT model to use
    • audioToTranscribe (bytes): Audio data to transcribe
    • language (string): Language code (ISO-639-1, defaults to "en")
    • format (string): Audio format
    • toString (boolean): Return plain text
    • toCaptions (boolean): Return timestamped captions

  • image (object): Image generation configuration

    • model (string): Image generation model
    • size (string): Generated image size

  • sendImage (object): Send images to multimodal LLMs

    • imagesData (array of bytes): Image data to send

Language-Specific Examples​

The following examples demonstrate how to create a definition for a mechanics object with nested properties across different programming languages:

{
  "type": "object",
  "instruction": "Represents the fundamental laws and systems governing the world.",
  "properties": {
    "lawsOfNature": {
      "type": "string",
      "instruction": "A description of the natural laws that govern the physical universe, such as gravity, thermodynamics, and other scientific principles."
    },
    "magic": {
      "type": "object",
      "instruction": "A detailed description of the magical systems and rules within the world.",
      "properties": {
        "source": {
          "type": "string",
          "instruction": "What is the origin of magical power in this world?"
        }
      }
    }
  }
}

Auxiliary Structures​

Focus (Narrow Focus)​

Allows sending a focused request to an LLM with minimal context.

Fields:

  • prompt (string): The prompt sent to the LLM
  • fields (array of strings): The properties to extract and their order
  • keepOriginal (boolean): Keep the original prompt in cases for lists where it would otherwise be removed from context

RequestFormat​

Defines the structure of an external request for data fetching.

Fields:

  • url (string): The endpoint to send the request to
  • method (string): The HTTP method to use for the request
  • headers (object): Optional headers to include in the request
  • body (object): Optional body content for the request
  • authorization (string): Optional authorization token
  • requireFields (array of strings): Fields that are required from the response

HashMap​

Used to create and return a map of values, useful in the instruction creation process.

Fields:

  • keyInstruction (string): Instruction for generating the map key
  • fieldDefinition (Definition): The definition for the map values

EpistemicValidation​

Configures epistemic validation to assess information validity.

Fields:

  • active (boolean): Whether epistemic validation is active for this field
  • judges (integer): Number of judges to validate the information

ModelConfig​

Advanced configuration for LLM model behavior.

Fields:

  • maxCompletionTokens (integer): Upper bound for tokens including output and reasoning tokens
  • temperature (float): Controls randomness (0.0 to 2.0)
  • topP (float): Nucleus sampling parameter
  • n (integer): Number of completions to generate
  • stream (boolean): Enable streaming responses
  • stop (array of strings): Sequences where generation should stop
  • presencePenalty (float): Penalty for token presence (-2.0 to 2.0)
  • frequencyPenalty (float): Penalty for token frequency (-2.0 to 2.0)
  • seed (integer): Random seed for deterministic outputs
  • logitBias (object): Token ID bias adjustments (must use token IDs, not words)
  • logProbs (boolean): Return log probabilities of output tokens
  • topLogProbs (integer): Number of most likely tokens to return (0-5)
  • user (string): User identifier for tracking
  • store (boolean): Store output for distillations and evals
  • reasoningEffort (string): Controls reasoning effort ("low", "medium", "high")
  • metadata (object): Additional metadata to store with completion
  • chatTemplateKwargs (object): Non-standard parameters for template renderer

DecisionPoint​

Enables conditional branching based on scores or field values for complex decision trees.

Fields:

  • name (string): Identifier for debugging and logging
  • evaluationPrompt (string): Guides the LLM in scoring the current generation
  • branches (array of ConditionalBranch): Conditional paths evaluated in order
  • strategy (RoutingStrategy): How conditions are evaluated ("score", "field", "hybrid")

Routing Strategies:

  • score: Uses LLM evaluation scores from ScoringCriteria
  • field: Uses values extracted via SelectFields
  • hybrid: Combines both score-based and field-based conditions

ConditionalBranch​

Represents an if/then rule in the decision tree.

Fields:

  • name (string): Branch identifier for debugging
  • conditions (array of Condition): ALL must be true (AND logic)
  • logic (Definition): Evaluation logic for the generated content
  • then (Definition): Definition to generate if conditions match
  • priority (integer): Evaluation order (higher priority evaluated first)

Condition​

Represents a single evaluation rule in a conditional expression.

Fields:

  • field (string): Name of the score or value to check
  • operator (ComparisonOperator): Comparison operation to perform
  • value (any): Value to compare the field against
  • fieldPath (string): Full path for nested field access (e.g., "requirements.is_technical")

Comparison Operators:

  • eq: Equal (==)
  • neq: Not equal (!=)
  • gt: Greater than (>)
  • lt: Less than (<)
  • gte: Greater than or equal (>=)
  • lte: Less than or equal (<=)
  • in: Value is in a list
  • nin: Value is not in a list
  • contains: String contains substring

ScoringCriteria​

Defines how to evaluate the quality of a generated field using an LLM as a judge.

Fields:

  • dimensions (object): Map of score names to evaluation definitions
  • evaluationModel (string): Which LLM model to use for scoring
  • aggregationMethod (AggregationMethod): How to combine dimension scores

Aggregation Methods:

  • weighted_average: Weighted average of all dimension scores
  • minimum: Lowest score across all dimensions
  • maximum: Highest score across all dimensions
  • custom: Custom aggregation logic

ScoringDimension​

Defines a single evaluation metric for quality assessment.

Fields:

  • description (string): Guides LLM on how to evaluate this dimension
  • scale (ScoreScale): Numeric range for scores (min/max)
  • type (ScoreType): Kind of score ("numeric", "boolean", "categorical")
  • weight (float): Weight for aggregation (0.0-1.0, should sum to 1.0)

Score Types:

  • numeric: Numeric score within a scale (e.g., 0-100)
  • boolean: Binary true/false evaluation
  • categorical: Categorical value (e.g., "low", "medium", "high")

RecursiveLoop​

Enables iterative refinement by generating a field multiple times.

Fields:

  • maxIterations (integer): Maximum number of generation attempts
  • selection (SelectionStrategy): Which iteration to keep as final result
  • terminationPoint (DecisionPoint): Conditions to stop early
  • feedbackPrompt (string): Guides improvement between iterations
  • includePreviousAttempts (boolean): Show LLM all previous iterations

Selection Strategies:

  • highest: Keep iteration with best (highest) aggregate score
  • lowest: Keep iteration with worst (lowest) aggregate score
  • latest: Keep most recent iteration
  • first: Keep first successful iteration
  • all: Return all iterations as an array

TextToSpeech​

Configuration for text-to-speech processing. Note: Use type "byte" with this feature.

Fields:

  • model (string): The text-to-speech model to use
  • stringToAudio (string): The text content to convert to speech
  • voice (string): The voice to use for synthesis
  • format (string): The audio format (e.g., mp3, wav)

SpeechToText​

Configuration for speech-to-text processing.

Fields:

  • model (string): The speech-to-text model to use
  • audioToTranscribe (bytes): The audio data to transcribe
  • language (string): Language code in ISO-639-1 format (defaults to "en")
  • format (string): The audio format
  • toString (boolean): Whether to return plain text
  • toCaptions (boolean): Whether to return timestamped captions

Image​

Configuration for image generation.

Fields:

  • model (string): The image generation model to use
  • size (string): The size of the generated image

SendImage (Vision Support)​

Configuration for sending images to multimodal LLMs.

Fields:

  • imagesData (array of bytes): The image data to send to the LLM

Example: Creating a Book Definition​

Below is an example of constructing a book definition using nested definitions for pages and chapters.

Go SDK Example​

func CreateBookDefinition(writingStyle, projectId, systemPrompt string) *Definition {

    // Definition for a page
    pageDefinition := Definition{
        Type:        Object,
        Instruction: "Create the details and information for a single page within a book.",
        Properties: map[string]Definition{
            "outline": {
                Type:        String,
                Instruction: "Create a detailed overview of the content for this page.",
            },
            "finalContent": {
                Type: String,
                Req: &RequestFormat{
                    URL:           "http://localhost:8001/getData",
                    Method:        POST,
                    Body:          map[string]interface{}{"projectId": projectId},
                    Authorization: fmt.Sprintf("Bearer %s", os.Getenv("API_KEY")),
                },
                Instruction: fmt.Sprintf(`
Create a vivid and immersive page for a fiction book based on the outline provided. Focus on detailed descriptions and engaging dialogue. 
Writing Style: %s
Minimum word count: 400 words.
`, writingStyle),
            },
            "editedContent": {
                Type: String,
                NarrowFocus: &Focus{
                    Prompt: "Format the page contents into paragraphs, maintaining all existing content.",
                    Fields: []string{"finalContent"},
                },
                SystemPrompt: &systemPrompt,
            },
        },
    }

    // Definition for a chapter
    chapterDefinition := Definition{
        Type:        Object,
        Instruction: "Create the details of the chapter, ensuring a cohesive story.",
        Properties: map[string]Definition{
            "title": {
                Type:        String,
                Instruction: "Create a chapter title with a maximum of 5 words.",
            },
            "outline": {
                Type:        String,
                Instruction: "Create a chapter outline detailing the events of the chapter.",
            },
            "pages": {
                Type:        Array,
                Items:       &pageDefinition,
                Instruction: "Create a list of pages, each logically leading to the next.",
            },
        },
    }

    // Definition for a book
    bookDefinition := Definition{
        Type:        Object,
        Instruction: "Create an engaging fictional story based on the provided outline.",
        Properties: map[string]Definition{
            "title": {
                Type:        String,
                Instruction: "Return a book title that encapsulates the story in a maximum of 5 words.",
            },
            "chapters": {
                Type:        Array,
                Items:       &chapterDefinition,
                Instruction: "Using the story outline, create a list of chapters detailing the narrative.",
            },
        },
    }

    return &bookDefinition
}

Best Practices​

  • Field Naming: Use camelCase for field names for consistency across languages
  • Types: Choose appropriate types for each field (e.g., string, number, boolean, object, array)
  • Clear Instructions: Provide clear and specific instructions for each field to guide the LLM
  • Reusability: Break down complex definitions into smaller, reusable components
  • Consistent Formatting: Ensure consistent structure and formatting for readability

Useful Tips​

  • Instruction field for Arrays: This field serves as the prompt that guides the object generation architecture in determining what values should populate the list
  • Field Names: Avoid using field names that would confuse an LLM. Maintain good naming conventions to help the LLM understand the structure
  • Instruction Field: Treat the instruction field as the prompt you want for generation. Having a clear instruction for an overall object gives the LLM insight into how the structure should look
  • Dynamic Instructions: To incorporate user inputs programmatically, create wrapper functions around the definition that accept relevant parameters and inject them into the instructions
  • Processing Order: Use the processingOrder field when fields have dependencies on other fields that must be generated first

Priority Levels​

When setting the priority field, use these standard values:

  • 2 (Urgent): Highest priority, takes precedence over all other requests
  • 1 (Standard): Default priority for most requests
  • 0 (Low): Low priority requests
  • -1 (Eventual): For batch LLM usage

Additional Resources​

For complete implementation examples and SDK-specific details, please refer to:

By following these guidelines, you can create well-structured and effective definitions regardless of which SDK you're using.