コンテンツにスキップ

API Reference

This page provides detailed API reference for the Refinire package's main components.

Classes and Functions Overview

Name Type Description
get_llm Function Get LLM instance from model name and provider
create_simple_gen_agent Function Create a simple generation agent
create_evaluated_gen_agent Function Create a generation agent with evaluation capabilities
Flow Class Central workflow management class
GenAgent Class Agent class with generation and evaluation capabilities
ClarifyAgent Class Interactive task clarification agent
Context Class Context for sharing state between steps
ConsoleTracingProcessor Class Console colored trace output processor
enable_console_tracing Function Enable console tracing functionality
disable_tracing Function Disable all tracing functionality
AgentPipeline Class [Deprecated] Integrated pipeline for generation, evaluation, tools, and guardrails

Unified LLM Interface

get_llm

Factory function for handling multiple LLM providers with a unified interface.

from refinire import get_llm

# OpenAI
llm = get_llm("gpt-4o-mini")

# Anthropic Claude
llm = get_llm("claude-3-sonnet")

# Google Gemini
llm = get_llm("gemini-pro")

# Ollama (Local)
llm = get_llm("llama3.1:8b")

Parameters

Name Type Required/Optional Default Description
model str Required - LLM model name to use
provider str Optional None Model provider name (auto-inferred if None)
temperature float Optional 0.3 Sampling temperature (0.0-2.0)
api_key str Optional None Provider API key
base_url str Optional None Provider API base URL
thinking bool Optional False Claude model thinking mode
tracing bool Optional False Enable Agents SDK tracing

Returns

  • LLM Instance: LLM object for the specified provider

Supported Models

OpenAI - gpt-4o, gpt-4o-mini - gpt-4-turbo, gpt-4 - gpt-3.5-turbo

Anthropic Claude - claude-3-5-sonnet-20241022 - claude-3-sonnet, claude-3-haiku - claude-3-opus

Google Gemini - gemini-pro, gemini-pro-vision - gemini-1.5-pro, gemini-1.5-flash

Ollama - llama3.1:8b, llama3.1:70b - mistral:7b - codellama:7b


Agent Creation Functions

create_simple_gen_agent

Creates a simple generation agent.

from refinire import create_simple_gen_agent

agent = create_simple_gen_agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    model="gpt-4o-mini"
)

Parameters

Name Type Required/Optional Default Description
name str Required - Agent name
instructions str Required - System prompt
model str Required - Model name to use
tools list Optional None List of available tools

create_evaluated_gen_agent

Creates a generation agent with evaluation capabilities.

from refinire import create_evaluated_gen_agent

agent = create_evaluated_gen_agent(
    name="quality_assistant",
    generation_instructions="Generate helpful responses.",
    evaluation_instructions="Evaluate accuracy and usefulness.",
    threshold=80.0,
    model="gpt-4o-mini"
)

Parameters

Name Type Required/Optional Default Description
name str Required - Agent name
generation_instructions str Required - Generation system prompt
evaluation_instructions str Required - Evaluation system prompt
threshold float Required - Quality threshold (0-100)
model str Required - Model name to use
tools list Optional None List of available tools

Flow/Step Architecture

Flow

Central workflow management class. Create complex processing flows by combining multiple steps.

from refinire import Flow, FunctionStep
import asyncio

# Simple Flow
flow = Flow(steps=gen_agent)

# Multi-step Flow
flow = Flow([
    ("step1", FunctionStep("step1", func1)),
    ("step2", FunctionStep("step2", func2))
])

# Execute
result = asyncio.run(flow.run(input_data="input data"))

Main Methods

Method Name Parameters Return Value Description
run input_data: Any Context Execute workflow asynchronously
run_sync input_data: Any Context Execute workflow synchronously
show - None Visualize workflow structure

Context

Context class for sharing state between steps.

from refinire import Context

ctx = Context()
ctx.shared_state["key"] = "value"
ctx.finish()  # End workflow

Main Attributes and Methods

Name Type Description
shared_state dict State shared between steps
user_input Any User input data
finish() Method Signal workflow completion

Agent Classes

GenAgent

Agent class with generation and evaluation capabilities. Can be used as a step within Flow.

from refinire.agents import GenAgent

agent = GenAgent(
    name="generator",
    generation_instructions="Generate text.",
    evaluation_instructions="Evaluate quality.",
    model="gpt-4o-mini",
    threshold=75.0
)

Main Methods

Method Name Parameters Return Value Description
run user_input: str, ctx: Context Context Execute agent asynchronously
run_sync user_input: str, ctx: Context Context Execute agent synchronously

ClarifyAgent

Interactive task clarification agent. Asks questions to clarify unclear requests.

from refinire.agents import ClarifyAgent

agent = ClarifyAgent(
    name="clarifier",
    instructions="Clarify user requirements.",
    model="gpt-4o-mini"
)

Tracing Functionality

enable_console_tracing

Enable colored console tracing.

from refinire import enable_console_tracing

enable_console_tracing()

disable_tracing

Disable all tracing functionality.

from refinire import disable_tracing

disable_tracing()

ConsoleTracingProcessor

Class for custom trace processing.

from refinire.tracing import ConsoleTracingProcessor

processor = ConsoleTracingProcessor(
    output_stream="console",
    simple_mode=True
)

Deprecated APIs

AgentPipeline (Deprecated)

⚠️ Important: AgentPipeline will be removed in v0.1.0. Use GenAgent + Flow for new code.

# Deprecated - Do not use in new code
from refinire import AgentPipeline

pipeline = AgentPipeline(
    name="example",
    generation_instructions="Generate text.",
    evaluation_instructions="Evaluate quality.",
    model="gpt-4o-mini",
    threshold=80
)

Architecture Diagram

classDiagram
    class Flow {
        +run(input_data)
        +run_sync(input_data)
        +show()
    }

    class GenAgent {
        +run(user_input, ctx)
        +run_sync(user_input, ctx)
    }

    class ClarifyAgent {
        +run(user_input, ctx)
        +clarify_task(task)
    }

    class Context {
        +shared_state: dict
        +user_input: Any
        +finish()
    }

    Flow --> GenAgent
    Flow --> ClarifyAgent
    Flow --> Context
    GenAgent --> Context
    ClarifyAgent --> Context

Usage Examples

Basic Usage Pattern

from refinire import create_simple_gen_agent, Flow, Context
import asyncio

# 1. Create agent
agent = create_simple_gen_agent(
    name="assistant",
    instructions="Respond as a helpful assistant.",
    model="gpt-4o-mini"
)

# 2. Create flow
flow = Flow(steps=agent)

# 3. Execute
async def main():
    result = await flow.run(input_data="Hello")
    print(result.shared_state["assistant_result"])

asyncio.run(main())

Complex Workflow Example

from refinire import Flow, FunctionStep, create_evaluated_gen_agent
import asyncio

def preprocess(user_input: str, ctx: Context) -> Context:
    ctx.shared_state["processed_input"] = user_input.strip().lower()
    return ctx

agent = create_evaluated_gen_agent(
    name="analyzer",
    generation_instructions="Analyze the input.",
    evaluation_instructions="Evaluate analysis accuracy.",
    threshold=80.0,
    model="gpt-4o-mini"
)

def postprocess(user_input: str, ctx: Context) -> Context:
    result = ctx.shared_state.get("analyzer_result", "")
    ctx.shared_state["final_result"] = f"Final result: {result}"
    ctx.finish()
    return ctx

flow = Flow([
    ("preprocess", FunctionStep("preprocess", preprocess)),
    ("analyze", agent),
    ("postprocess", FunctionStep("postprocess", postprocess))
])

async def main():
    result = await flow.run(input_data="  Analyze this text  ")
    print(result.shared_state["final_result"])

asyncio.run(main())

ContextProvider Interface

Class/Method Description (EN) Arguments / Returns
ContextProvider Abstract base for all context providers.
provider_name Provider name (class variable). str
get_config_schema Returns config schema for the provider. classmethodDict[str, Any]
from_config Instantiates provider from config dict. classmethod → instance
get_context Returns context string for a query. query: str, previous_context: Optional[str], **kwargsstr
update Updates provider state with new interaction. interaction: Dict[str, Any]
clear Clears provider state.

Built-in Providers

ConversationHistoryProvider

Manages conversation history.

Configuration Example:

{
    "type": "conversation_history",
    "max_items": 10
}

Parameters: - max_items (int): Maximum number of messages to keep (default: 10)

FixedFileProvider

Always provides content from specified files.

Configuration Example:

{
    "type": "fixed_file",
    "file_path": "config.yaml",
    "encoding": "utf-8",
    "check_updates": True
}

Parameters: - file_path (str, required): Path to the file to read - encoding (str): File encoding (default: "utf-8") - check_updates (bool): Whether to check for file updates (default: True)

SourceCodeProvider

Automatically searches for source code related to user questions.

Configuration Example:

{
    "type": "source_code",
    "base_path": ".",
    "max_files": 5,
    "max_file_size": 1000,
    "file_extensions": [".py", ".js", ".ts"],
    "include_patterns": ["src/**/*"],
    "exclude_patterns": ["tests/**/*"]
}

Parameters: - base_path (str): Base directory path for codebase analysis (default: ".") - max_files (int): Maximum number of files to include in context (default: 50) - max_file_size (int): Maximum file size in bytes to read (default: 10000) - file_extensions (list): List of file extensions to include - include_patterns (list): List of patterns to include - exclude_patterns (list): List of patterns to exclude

CutContextProvider

Compresses context to specified length.

Configuration Example:

{
    "type": "cut_context",
    "provider": {
        "type": "source_code",
        "max_files": 10,
        "max_file_size": 2000
    },
    "max_chars": 3000,
    "max_tokens": None,
    "cut_strategy": "middle",
    "preserve_sections": True
}

Parameters: - provider (dict, required): Configuration for the wrapped context provider - max_chars (int): Maximum character count (None for no limit) - max_tokens (int): Maximum token count (None for no limit) - cut_strategy (str): How to cut the context ("start", "end", "middle") (default: "end") - preserve_sections (bool): Whether to preserve complete sections when cutting (default: True)


RefinireAgent Extensions

Class/Method Description (EN) Arguments / Returns
context_providers_config List/dict/YAML string for context provider config. List[dict]/str
get_context_provider_schemas Returns schemas for all available providers. classmethodDict[str, Any]
clear_context Clears all context providers.

Example: Using SourceCodeProvider

from refinire.agents.context_provider_factory import ContextProviderFactory

config = {
    "type": "source_code",
    "base_path": "src",
    "max_files": 5
}
provider = ContextProviderFactory.create_provider(config)
context = provider.get_context("How does the pipeline work?")
print(context)

Example: YAML-like Multi-provider

- conversation_history:
    max_items: 5
- source_code:
    base_path: src
    max_files: 3
- cut_context:
    provider:
      type: conversation_history
      max_items: 10
    max_chars: 4000
    cut_strategy: end

See Also

  • docs/api_reference_ja.md (Japanese)
  • docs/context_management.md (Design)
  • examples/context_management_example.py (Usage)