Fence

https://github.com/wouterdurnez/fence
Admin
Fence is a lightweight, production-ready library for LLM communication and agentic workflows with...
Tokens:46,835
Snippets:428
Trust Score:7.1
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Complete MCP Client Example with Agent

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MCP.md

Full example demonstrating MCP client initialization with Streamable HTTP, event handlers, and agent usage. Includes logging and error handling.

```python
from fence.agents.bedrock import BedrockAgent
from fence.mcp.client import MCPClient
from fence.models.bedrock import Claude37Sonnet
from fence.utils.logger import setup_logging

# Setup logging
logger = setup_logging(log_level="info")

# Create MCP client
mcp_client = MCPClient(
    transport_type="streamable_http",
    url="https://crm-mcp-server.internal.company.com/mcp",
    headers={
        "X-API-Key": "your-api-key",
        "X-User-Context": "user_session_token"
    },
    read_timeout_seconds=60
)

# Define event handlers
def on_thinking(text: str):
    print(f"🤔 Thinking: {text[:100]}...")

def on_tool_use_start(tool_name: str, parameters: dict):
    print(f"🔧 Using MCP tool: {tool_name}")

def on_tool_use_stop(tool_name: str, parameters: dict, result: dict):
    print(f"✅ Tool completed: {tool_name}")

# Create agent
agent = BedrockAgent(
    identifier="crm_assistant",
    model=Claude37Sonnet(region="us-east-1", cross_region="us"),
    mcp_clients=[mcp_client],
    system_message="""You are a CRM assistant with access to customer data.
    Use the available tools to help users with their queries.
    Always explain what you're doing and why.""",
    event_handlers={
        "on_thinking": on_thinking,
        "on_tool_use_start": on_tool_use_start,
        "on_tool_use_stop": on_tool_use_stop,
    },
    log_agentic_response=True
)

# Use the agent
try:
    result = agent.run("Find all opportunities for Acme Corporation")
    print(f"\n🎉 Answer: {result.answer}")
except Exception as e:
    logger.error(f"Error: {e}")
finally:
    # Clean up
    agent.cleanup()
```

--------------------------------

### Hello World Example: Generate a Haiku

Source: https://github.com/wouterdurnez/fence/blob/main/README.md

A basic example demonstrating how to create and run a 'Link' to generate a haiku about a given topic using GPT-4-omini and StringTemplate.

```python
from fence.links import Link
from fence.templates.string import StringTemplate
from fence.models.openai import GPT4omini

# Create a link
link = Link(
    model=GPT4omini(),
    template=StringTemplate("Write a haiku about {topic}"),
    name='haiku_generator'
)

# Run it
output = link.run(topic='fencing')['state']
print(output)
```

```text
[2024-10-04 17:45:15] [ℹ️ INFO] [links.run:203]              Executing <haiku_generator> Link
Blades flash in the light,
En garde, the dance begins now,
Touch—victory's mine.
```

--------------------------------

### Environment Setup and Imports

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/structured_output_demo.ipynb

Sets up the environment by adding the project directory to sys.path and loading extensions. Imports necessary Pydantic and Fence modules.

```python
from pathlib import Path
current_dir = Path('.').resolve().parents[0]
import sys
sys.path.append(str(current_dir))

%load_ext autoreload
%autoreload 2
```

```python
from pydantic import BaseModel, Field
from typing import List
from fence.models.bedrock import NovaPro
from fence.links import Link
from fence.chains import Chain
from fence.templates.string import StringTemplate
```

--------------------------------

### Render StringTemplate with Dictionary (Duplicate Example)

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Renders a string template with a dictionary. This example is a duplicate of a previous rendering demonstration.

```python
prompt_template_test = StringTemplate('Why is the sky {color}?')
print(prompt_template_test.render({'color': 'blue'}))
```

--------------------------------

### Install Fence Dependencies

Source: https://github.com/wouterdurnez/fence/blob/main/CONTRIBUTING.md

Install the project dependencies using Poetry. The --no-root flag is used to install only the dependencies, not the project itself.

```sh
poetry install --no-root
```

--------------------------------

### Uniform Model Interface Example

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Demonstrates the uniform interface across different model providers (Bedrock, OpenAI, Gemini) by iterating through a list of models and sending the same prompt to each.

```python
# All of these work the same way!
from fence.models.bedrock import Claude35Sonnet
from fence.models.openai import GPT4o
from fence.models.gemini import GeminiFlash2_0

models = [
    Claude35Sonnet(source="comparison"),
    GPT4o(source="comparison"),
    GeminiFlash2_0(source="comparison")
]

prompt = "What is the capital of France?"

for model in models:
    response = model(prompt)  # Same interface!
    print(f"{model.model_name}: {response}")
```

--------------------------------

### Real-World Example: Customer Support Bot Agent Creation

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MEMORY.md

Demonstrates creating a customer support agent with persistent DynamoDB memory, specifying the model, role, and max memory size.

```python
from fence.agents import Agent
from fence.memory import DynamoDBMemory
from fence.models.bedrock import Claude35Sonnet

def create_support_agent(user_id: str, session_id: str) -> Agent:
    """Create a customer support agent with persistent memory."""

    # Create persistent memory for this user session
    memory = DynamoDBMemory(
        table_name="customer-support-memory",
        primary_key_name="session_id",
        primary_key_value=f"user_{user_id}_session_{session_id}"
    )

    # Create agent
    agent = Agent(
        identifier="support_agent",
        model=Claude35Sonnet(region="us-east-1"),
        memory=memory,
        role="""You are a helpful customer support agent.
        You remember previous conversations with the customer.
        Always be polite and professional.""",
        max_memory_size=5000  # Limit context size
    )

    return agent

# Usage
agent = create_support_agent(user_id="12345", session_id="abc-def")

# First interaction
agent.run("I'm having trouble with my order #98765")

# Later interaction (same session)
agent.run("What was my order number again?")
# "Your order number is #98765"

# Different session
new_agent = create_support_agent(user_id="12345", session_id="xyz-123")
new_agent.run("Hello")  # Fresh conversation, no memory of previous session
```

--------------------------------

### Multi-Level Agent Delegation Example

Source: https://github.com/wouterdurnez/fence/blob/main/docs/AGENTS.md

Demonstrate how agents can delegate tasks to other specialized agents. A coordinator agent delegates mathematical questions to a dedicated mathematician agent.

```python
from fence.agents import Agent
from fence.tools.math import CalculatorTool, PrimeTool
from fence.tools.text import SecretStringTool

# Create a specialist agent
math_agent = Agent(
    identifier="mathematician",
    model=GPT4omini(source="agent"),
    description="An agent specialized in mathematical operations",
    tools=[CalculatorTool(), PrimeTool()]
)

# Create a coordinator agent
coordinator = Agent(
    identifier="coordinator",
    model=GPT4omini(source="agent"),
    description="A coordinator that can delegate to specialists",
    delegates=[math_agent],
    tools=[SecretStringTool()]
)

# The coordinator will delegate math questions to the specialist
result = coordinator.run("Is 17 a prime number? Also, what's the secret string?")
```

--------------------------------

### Basic RoundTable Setup and Execution

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MULTI_AGENT.md

Demonstrates how to create specialized ChatAgents with unique profiles and orchestrate them using the RoundTable pattern to discuss a given prompt. Requires the fence library and an OpenAI model.

```python
from fence.troupe import RoundTable
from fence.agents import ChatAgent
from fence.models.openai import GPT4omini

# Create specialized agents
detective = ChatAgent(
    identifier="Detective",
    model=GPT4omini(source="roundtable"),
    profile="You are a sharp detective who analyzes clues carefully."
)

scientist = ChatAgent(
    identifier="Scientist",
    model=GPT4omini(source="roundtable"),
    profile="You are a forensic scientist who examines evidence."
)

witness = ChatAgent(
    identifier="Witness",
    model=GPT4omini(source="roundtable"),
    profile="You are a nervous witness who saw something suspicious."
)

# Create the round table
round_table = RoundTable(agents=[detective, scientist, witness])

# Start the discussion
transcript = round_table.run(
    prompt="A valuable painting was stolen from the museum. Let's investigate!",
    max_rounds=3
)

print(transcript)
```

--------------------------------

### Install Fence LLM Package

Source: https://github.com/wouterdurnez/fence/blob/main/README.md

Install the Fence LLM package using pip. This is a straightforward installation with minimal dependencies.

```bash
pip install fence-llm
```

--------------------------------

### DynamoDB Memory Setup

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MEMORY.md

Provides the bash command to create an AWS DynamoDB table for agent memory. This table uses 'session_id' as the primary key.

```bash
aws dynamodb create-table \
    --table-name agent-memory \
    --attribute-definitions \
        AttributeName=session_id,AttributeType=S \
    --key-schema \
        AttributeName=session_id,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST
```

--------------------------------

### Initialize Agent with Prefilled Memory

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MEMORY.md

Start an agent's conversation with predefined context by providing an initial message. The agent will begin its interaction with this prefilled content.

```python
agent = Agent(
    identifier="prefilled_agent",
    model=GPT4omini(source="app"),
    memory=FleetingMemory(),
    prefill="I understand. I'll help you with that."
)

# Agent starts with the prefilled message
```

--------------------------------

### Example Output Dictionary

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

This dictionary represents the output from a chain execution, containing various keys and their corresponding string values, including a formatted poem.

```python
Output:
{'A': 'A police officer',
 'B': 'Hopeful',
 'C': 'A criminal. and Optimistic.',
 'X': 'A criminal.',
 'Y': 'Optimistic.',
 'Z': "**The Optimist's Crime**\n"
      '\n'
      'In shadows deep where silence hides,  \n'
      'A criminal’s heart still beats, it bides,  \n'
      'With dreams that sparkle like stars above,  \n'
      'Whispers of hope, a longing for love.  \n'
      '\n'
      'He prowls the streets with a crooked smile,  \n'
      'Yet in his chest, a spark worthwhile,  \n'
      'For every heist, a tale of grace,  \n'
      'A wish for redemption, a chance to embrace.  \n'
      '\n'
      'With fingers stained by the sins of night,  \n'
      'He counts his fortunes with fingers tight,  \n'
      'But in his eyes, a glimmering thread,  \n'
      'Of laughter, of joy, of paths ahead.  \n'
      '\n'
      'He dreams of a life where wrong becomes right,  \n'
      'Where burdens lift softly like clouds taking flight,  \n'
      'Each stolen moment a lesson learned,  \n'
      "In the furnace of life, it's how we are burned.  \n"
      '\n'
      'For in every shadow, a light does gleam,  \n'
      'A flicker of hope in the darkest dream,  \n'
      "So here's to the criminal, lost yet found,  \n"
      'With every misstep, he dances around.  \n'
      '\n'
      'For in every crime, an ambition does speak,  \n'
      'A testament to those who feel weak,  \n'
      'With dreams like wildflowers breaking through stone,  \n'
      'Even in chaos, we’re never alone.  ',
 'state': "**The Optimist's Crime**\n"
          '\n'
          'In shadows deep where silence hides,  \n'
          'A criminal’s heart still beats, it bides,  \n'
          'With dreams that sparkle like stars above,  \n'
          'Whispers of hope, a longing for love.  \n'
          '\n'
          'He prowls the streets with a crooked smile,  \n'
          'Yet in his chest, a spark worthwhile,  \n'
          'For every heist, a tale of grace,  \n'
          'A wish for redemption, a chance to embrace.  \n'
          '\n'
          'With fingers stained by the sins of night,  \n'
          'He counts his fortunes with fingers tight,  \n'
          'But in his eyes, a glimmering thread,  \n'
          'Of laughter, of joy, of paths ahead.  \n'
          '\n'
          'He dreams of a life where wrong becomes right,  \n'
          'Where burdens lift softly like clouds taking flight,  \n'
          'Each stolen moment a lesson learned,  \n'
          "In the furnace of life, it's how we are burned.  \n"
          '\n'
          'For in every shadow, a light does gleam,  \n'
          'A flicker of hope in the darkest dream,  \n'
          "So here's to the criminal, lost yet found,  \n"
          'With every misstep, he dances around.  \n'
          '\n'
          'For in every crime, an ambition does speak,  \n'
          'A testament to those who feel weak,  \n'
          'With dreams like wildflowers breaking through stone,  \n'
          'Even in chaos, we’re never alone.  '}
```

--------------------------------

### Customer Support Chain Example

Source: https://github.com/wouterdurnez/fence/blob/main/docs/LINKS_AND_CHAINS.md

This Python snippet shows how to construct a chain of links for a customer support workflow. It includes extracting information, checking urgency, and generating a response using different language models.

```python
from fence.chains import Chain
from fence.links import Link
from fence.templates.string import StringTemplate
from fence.parsers import TOMLParser, BoolParser
from fence.models.bedrock import ClaudeHaiku, Claude35Sonnet

# Step 1: Extract customer info
info_extractor = Link(
    model=ClaudeHaiku(),
    template=StringTemplate("""
    Extract customer information from this email:
    {email}

    Return in TOML format:
    name = "..."
    email = "..."
    issue = "..."
    """),
    parser=TOMLParser(),
    name="info_extractor"
)

# Step 2: Check if urgent
urgency_checker = Link(
    model=ClaudeHaiku(),
    template=StringTemplate("""
    Is this issue urgent? Answer true or false.
    Issue: {issue}
    """),
    parser=BoolParser(),
    name="urgency_checker"
)

# Step 3: Generate response
response_generator = Link(
    model=Claude35Sonnet(),
    template=StringTemplate("""
    Generate a professional response to this customer:
    Name: {name}
    Issue: {issue}
    Urgent: {urgent}
    """),
    name="response_generator"
)

# Create the chain
support_chain = Chain(links=[
    info_extractor,
    urgency_checker,
    response_generator
])

# Process customer email
result = support_chain.run(email="Customer email text...")
print(result['state'])  # Final response

```

--------------------------------

### Choosing Memory Backends

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MEMORY.md

Demonstrates initializing different memory backends for development, production (AWS DynamoDB), and local production (SQLite).

```python
# Development
dev_memory = FleetingMemory()

# Production (AWS)
prod_memory = DynamoDBMemory(
    table_name="prod-agent-memory",
    primary_key_name="session_id",
    primary_key_value=f"user_{user_id}"
)

# Local production
local_prod_memory = SQLiteMemory(
    db_path="/var/app/memory.db",
    session_id=f"user_{user_id}"
)
```

--------------------------------

### Initialize MCP Client with Streamable HTTP

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MCP.md

Use this for production environments. Configure with URL, headers, and read timeout.

```python
mcp_client = MCPClient(
    transport_type="streamable_http",
    url="https://api.example.com/mcp",
    headers={
        "Authorization": "Bearer your-token",
        "X-Custom-Header": "value"
    },
    read_timeout_seconds=60
)
```

--------------------------------

### Simple Agent with Tools

Source: https://github.com/wouterdurnez/fence/blob/main/README.md

Demonstrates creating a basic agent with a calculator tool. Use this for straightforward tasks requiring tool execution.

```python
from fence.agents import Agent
from fence.models.openai import GPT4omini
from fence.tools.math import CalculatorTool

agent = Agent(
    identifier="math_wizard",
    model=GPT4omini(source="demo"),
    tools=[CalculatorTool()],
)

result = agent.run("What is 1337 * 42 + 999?")
print(result)  # Agent thinks, uses calculator, and answers!
```

--------------------------------

### Retrieve Messages from Memory

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MEMORY.md

Get all messages currently stored in memory. Iterate through the messages to access their role and content.

```python
# Get all messages
messages = memory.get_messages()

for message in messages:
    print(f"{message.role}: {message.content}")
```

--------------------------------

### Create and Run a Basic Link

Source: https://github.com/wouterdurnez/fence/blob/main/docs/LINKS_AND_CHAINS.md

Instantiates a Link with a model and string template, then executes it with a topic.

```python
from fence.links import Link
from fence.templates.string import StringTemplate
from fence.models.openai import GPT4omini

# Create a link
link = Link(
    model=GPT4omini(),
    template=StringTemplate("Write a haiku about {topic}"),
    name='haiku_generator'
)

# Run it
result = link.run(topic='fencing')
print(result['state'])
```

--------------------------------

### Invoke model directly

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Demonstrates calling a language model directly using the 'invoke' method to get a response to a prompt.

```python
# Use the invoke method to call the model
model.invoke('Why is the sky blue?')
```

--------------------------------

### Configure Link Options

Source: https://github.com/wouterdurnez/fence/blob/main/docs/LINKS_AND_CHAINS.md

Demonstrates optional parameters for Link instantiation, including parser, name, callbacks, and metadata.

```python
link = Link(
    model=GPT4omini(),
    template=StringTemplate("Summarize: {text}"),
    parser=None,                    # Optional parser
    name='summarizer',              # Link name for logging
    callbacks=[my_callback],        # Optional callbacks
    metadata={'version': '1.0'}     # Optional metadata
)
```

--------------------------------

### Instantiate and Use OpenAI Models

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Shows how to instantiate and use various OpenAI models like GPT-4o, GPT-4o-mini, and GPT-4. Ensure the OPENAI_API_KEY environment variable is set.

```python
from fence.models.openai import GPT4o, GPT4omini, GPT4

# Use OpenAI models
model = GPT4omini(source="my_app")

response = model("Write a poem about AI")
```

--------------------------------

### Initialize MCP Client with SSE

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MCP.md

Configure for Server-Sent Events transport. Requires URL, headers, and read timeout.

```python
mcp_client = MCPClient(
    transport_type="sse",
    url="https://api.example.com/sse",
    headers={"Authorization": "Bearer your-token"},
    read_timeout_seconds=30
)
```

--------------------------------

### Agent Initialization with Tools

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/using _environment.ipynb

Initializes an agent with a specific language model and a list of available tools. This sets up the agent's capabilities for subsequent operations.

```python
 [1;32m[2025-04-24 11:08:44] [INFO] ℹ️ [agent.__init__:91] Initialized agent with model <GPT 4o mini>, delegates: [], tools: ['AccountNameRetrieverTool'] [0m
```

--------------------------------

### Crafting Specific Agent Profiles

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MULTI_AGENT.md

Define detailed and actionable profiles for agents to guide their behavior and expertise. Vague profiles can lead to generic or unhelpful responses.

```python
# Good - specific and actionable
profile = """You are a cybersecurity expert with 15 years of experience.
You focus on identifying vulnerabilities and suggesting mitigations.
You always consider both technical and business impacts."""

# Bad - too vague
profile = "You are an expert who knows things."
```

--------------------------------

### Basic BedrockAgent Initialization

Source: https://github.com/wouterdurnez/fence/blob/main/docs/AGENTS.md

Demonstrates how to create and run a basic BedrockAgent with a specific model and tool. Ensure the necessary tools and models are imported.

```python
from fence.agents.bedrock import BedrockAgent
from fence.models.bedrock import Claude35Sonnet
from fence.tools.text import TextInverterTool

# Create Bedrock agent
agent = BedrockAgent(
    identifier="text_processor",
    model=Claude35Sonnet(region="us-east-1"),
    tools=[TextInverterTool()],
    description="An agent that processes text"
)

result = agent.run("Invert the text: Hello World!")
print(result.answer)
```

--------------------------------

### Bedrock Agent Events Structure

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/using_bedrock_agents.ipynb

This snippet shows the structured output of Bedrock Agent events, including start, thinking, tool usage, and answer phases.

```text
[BedrockAgent [Start],
 BedrockAgent [Thinking] To find the weather in New York in Celsius, I need to first get the current weather in New York, which will likely be in Fahrenheit. Then, I need to convert that temperature from Fahrenheit to Celsius.,
 BedrockAgent [Tool_use] GetWeatherTool ({'location': 'New York'}) -> Sunny, 75°F,
 BedrockAgent [Thinking] Now that I have the current weather in New York, which is 75°F, I need to convert this temperature to Celsius using the <ConvertTemperatureTool>.,
 BedrockAgent [Tool_use] ConvertTemperatureTool ({'from_unit': 'Fahrenheit', 'to_unit': 'Celsius', 'value': 75}) -> 23.9°C,
 BedrockAgent [Answer] The weather in New York is sunny, with a temperature of 23.9°C.,
 BedrockAgent [Stop]]


```

--------------------------------

### Run Link with Sample Reviews

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/structured_output_demo.ipynb

Iterate through sample reviews and use the created Link to perform analysis. The structured data is accessed via the 'state' key in the result dictionary. This demonstrates how to process multiple inputs and retrieve parsed outputs.

```python
# Test with sample reviews
sample_reviews = [
    "This laptop is amazing! Super fast, great battery life, and the screen is gorgeous. Definitely worth the money. 5 stars!",
    "The phone is okay but the battery dies too quickly. Camera is decent though. Would give it 3 stars.",
    "Terrible product. Broke after one week. Customer service was unhelpful. Don't waste your money. 1 star.",
    "I switched from iPhone to this Samsung Galaxy and I'm impressed! The camera is better than my old iPhone 13, battery lasts all day, and the price was much more reasonable. The only downside is some apps work better on iOS, but overall very happy. 9/10!",
]

for i, review in enumerate(sample_reviews, 1):
    print(f"\n📝 Review {i}:")
    print(f"Text: {review}")

    result = review_analyzer.run(review_text=review)
    result = result[
        "state" 
    ]  # 🎯 Dictionary with 'state' key containing the structured data

    print(f"\n✨ Structured Analysis:")
    print(f"   Rating: {result['rating']}/5 ⭐")
    print(f"   Sentiment: {result['sentiment']} 😊")
    print(f"   Key Points: {', '.join(result['key_points'])} 📌")
    print(f"   Recommendation: {result['recommendation']} 💡")
```

--------------------------------

### Agent Initialization with Tools and Delegates

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/using _environment.ipynb

Initializes an agent with a specific model, tools, and delegates. This sets up the agent's capabilities for processing tasks.

```python
 [1;32m[2025-04-24 11:08:46] [INFO] ℹ️ [agent.__init__:91] Initialized agent with model <GPT 4o mini>, delegates: [], tools: ['AccountNameRetrieverTool'] [0m
 [1;32m[2025-04-24 11:08:46] [INFO] ℹ️ [agent.__init__:91] Initialized agent with model <GPT 4o mini>, delegates: ['child_accountant'], tools: [] [0m
```

--------------------------------

### Custom Parallel Document Processing

Source: https://github.com/wouterdurnez/fence/blob/main/docs/TOOLS_AND_UTILITIES.md

Run a custom document processing function in parallel. This example defines a 'process_document' function and applies it to a list of document IDs using the parallelize utility.

```python
def process_document(doc_id: str) -> dict:
    """Process a single document."""
    # Your processing logic
    return {"id": doc_id, "status": "processed"}

document_ids = ["doc1", "doc2", "doc3", "doc4", "doc5"]

results = parallelize(
    func=process_document,
    items=document_ids,
    max_workers=5
)
```

--------------------------------

### Initialize Logging and Model

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/using_callbacks.ipynb

Sets up the logging utility and initializes the GPT4omini model. Ensure these imports are present before registering callbacks or making model calls.

```python
from fence.models.openai.gpt import GPT4omini
from fence.models.base import register_log_callback, register_log_tags
from fence.utils.logger import setup_logging

logger = setup_logging(are_you_serious=False)
model = GPT4omini()
```

--------------------------------

### BedrockAgent with Custom System Messages

Source: https://github.com/wouterdurnez/fence/blob/main/docs/AGENTS.md

Shows how to provide a custom system message to guide the BedrockAgent's behavior and specialization. This allows for fine-tuning the agent's persona and task focus.

```python
agent = BedrockAgent(
    identifier="custom_agent",
    model=Claude35Sonnet(region="us-east-1"),
    system_message="""You are a helpful assistant specialized in data analysis.
    You have access to various tools and should use them when appropriate.
    Always explain your reasoning before taking action.""",
    tools=[CalculatorTool()]
)
```

--------------------------------

### Create and Use a Custom WeatherTool

Source: https://github.com/wouterdurnez/fence/blob/main/docs/TOOLS_AND_UTILITIES.md

Shows how to create a custom tool by extending BaseTool and integrate it with an agent.

```python
from fence.tools.base import BaseTool

class WeatherTool(BaseTool):
    """A tool that fetches weather information."""

    name = "get_weather"
    description = "Get current weather for a location"

    def __init__(self):
        super().__init__()
        self.parameters = {
            "location": {
                "type": "string",
                "description": "City name or zip code"
            },
            "units": {
                "type": "string",
                "description": "Temperature units (celsius or fahrenheit)",
                "enum": ["celsius", "fahrenheit"]
            }
        }

    def run(self, location: str, units: str = "celsius", **kwargs) -> str:
        """
        Fetch weather data.

        :param location: City name or zip code
        :param units: Temperature units
        :param kwargs: Additional arguments (includes 'environment')
        :return: Weather information
        """
        # Your implementation here
        # Access environment variables: kwargs.get('environment', {})

        return f"The weather in {location} is sunny and 72°{units[0].upper()}"

# Use with an agent
from fence.agents import Agent

agent = Agent(
    identifier="weather_agent",
    model=GPT4omini(source="app"),
    tools=[WeatherTool()]
)

result = agent.run("What's the weather in Paris?")
```

--------------------------------

### Create and Run a Simple Chain

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

This snippet demonstrates how to define a chain with two links, where the output of one link becomes the input for the next. It shows how to initialize links with string templates and run the chain with an initial input dictionary. It also includes basic error handling for potential exceptions during chain execution.

```python
# Cycles are not allowed
link_up = Link(
    template=StringTemplate(
        "Capitalize this word: {up}. Only respond with the capitalized version",
    ),
    name = 'up',
    output_key="down",
)
link_b = Link(
    template=StringTemplate(
        "What's a synonym for {down}. Reply with one word.", 
    ),
    name='down',
    output_key="up",
)
chain = Chain(model=model, links=[link_up, link_b])
try:
    chain.run(input_dict={"up": "happy"})
except Exception as e:
    print(e)
```

--------------------------------

### Parallelize Function Calls with Items

Source: https://github.com/wouterdurnez/fence/blob/main/docs/TOOLS_AND_UTILITIES.md

Use the parallelize utility to run a function on multiple items concurrently. This example processes a list of prompts in parallel using a specified number of worker threads.

```python
from fence.utils.optim import parallelize

# Process multiple prompts in parallel
prompts = [
    "Summarize: Article 1...",
    "Summarize: Article 2...",
    "Summarize: Article 3...",
]

results = parallelize(
    func=model.invoke,
    items=prompts,
    max_workers=3
)

for i, result in enumerate(results):
    print(f"Summary {i+1}: {result}")
```

--------------------------------

### Bedrock Agent Execution Log

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/using_bedrock_agents.ipynb

This snippet shows the detailed output of a Bedrock Agent performing a temperature conversion. It includes agent start, thought process, tool usage, and the final answer.

```text
 [1mBedrockAgent [0m 🚀  [96m[start] [0m Agent BedrockAgent started
 [1mBedrockAgent [0m 💭  [94m[thought] [0m To find the weather in New York in Celsius, I need to first get the current weather in New York, which will likely be in Fahrenheit. Then, I need to convert that temperature from Fahrenheit to Celsius.
 [1mBedrockAgent [0m 🔧  [38;5;208m[tool_use] [0m Using tool [GetWeatherTool] with parameters: {'location': 'New York'} -> Sunny, 75°F
 [1mBedrockAgent [0m 💭  [94m[thought] [0m Now that I have the current weather in New York, which is 75°F, I need to convert this temperature to Celsius using the <ConvertTemperatureTool>.
 [1mBedrockAgent [0m 🔧  [38;5;208m[tool_use] [0m Using tool [ConvertTemperatureTool] with parameters: {'from_unit': 'Fahrenheit', 'to_unit': 'Celsius', 'value': 75} -> 23.9°C
 [1mBedrockAgent [0m 🎯  [91m[answer] [0m The weather in New York is sunny, with a temperature of 23.9°C.
 [1mBedrockAgent [0m 🏁  [96m[stop] [0m Agent BedrockAgent stopped


Agent answer: The weather in New York is sunny, with a temperature of 23.9°C.



```

--------------------------------

### Step 1: Analyze Individual Reviews

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/structured_output_demo.ipynb

Creates a Link to analyze product reviews, defining the output structure as 'ProductReview'. This is the first step in a chain.

```python
# Step 1: Analyze individual reviews
review_model = NovaPro(source="chain_demo", region="us-east-1")

review_link = Link(
    model=review_model,
    template=StringTemplate(
        """
    Analyze this product review:
    \"{review_text}\""
    ),
    name="review_analyzer",
    output_key="review_analysis",
    output_structure=ProductReview,  # 🎯 Structured output defined in Link!
)

print("🔗 Step 1: Review analyzer created")
```

--------------------------------

### Retry API Calls with Exponential Backoff

Source: https://github.com/wouterdurnez/fence/blob/main/docs/TOOLS_AND_UTILITIES.md

Configure the retry decorator with exponential backoff to increase the delay between retries. This example retries up to 5 times, with delays increasing exponentially (1s, 2s, 4s, 8s).

```python
@retry(max_attempts=5, delay=1.0, backoff=2.0)
def api_call_with_backoff():
    """
    Retries with exponential backoff:
    - Attempt 1: immediate
    - Attempt 2: wait 1s
    - Attempt 3: wait 2s
    - Attempt 4: wait 4s
    - Attempt 5: wait 8s
    """
    return requests.get("https://api.example.com/data").json()
```

--------------------------------

### Initialize MCP Client with Stdio

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MCP.md

Use for local MCP servers running as subprocesses. Specify command and arguments.

```python
mcp_client = MCPClient(
    transport_type="stdio",
    command="python",
    args=["path/to/mcp_server.py"]
)
```

--------------------------------

### Retry API Calls with Max Attempts and Delay

Source: https://github.com/wouterdurnez/fence/blob/main/docs/TOOLS_AND_UTILITIES.md

Use the retry decorator to automatically retry a function that may fail due to transient issues. This example retries up to 3 times with a 1-second delay between attempts.

```python
from fence.utils.optim import retry

@retry(max_attempts=3, delay=1.0)
def flaky_api_call():
    """This function will retry up to 3 times with 1 second delay."""
    response = requests.get("https://api.example.com/data")
    response.raise_for_status()
    return response.json()

# Use it
try:
    data = flaky_api_call()
except Exception as e:
    print(f"Failed after 3 attempts: {e}")
```

--------------------------------

### Create and Run the Analysis Chain

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/structured_output_demo.ipynb

Assembles the individual links into a 'Chain' and runs it with sample input, then prints the final market insight.

```python
# Create the chain
analysis_chain = Chain(links=[review_link, competitor_link, insight_link])

print("⛓️ Analysis chain created with 3 structured output steps!")
print(f"🔗 Links: {[link.name for link in analysis_chain.links]}")

# Run the chain with a sample review
sample_review = """
I switched from iPhone to this Samsung Galaxy and I'm impressed! 
The camera is better than my old iPhone 13, battery lasts all day, 
and the price was much more reasonable. The only downside is some 
apps work better on iOS, but overall very happy. 4.5 stars!
"""

print(f"📱 Analyzing Review: {sample_review.strip()[:100]}...")
print("\n🔄 Running chain...")

result = analysis_chain.run(input_dict={"review_text": sample_review})
final_insight = result["state"]

print(f"\n🎯 Market Insight Generated:")
print(f"   📱 Product: {final_insight['product_name']}")
print(f"   ⭐ Overall Rating: {final_insight['overall_rating']}/5.0")
print(f"   😊 Sentiment: {final_insight['sentiment_summary']}")
print(f"   🏢 Top Competitors: {', '.join(final_insight['top_competitors'])}")
print(f"   💡 Recommendation: {final_insight['market_recommendation']}")
print(f"   📊 Total Reviews Analyzed: {final_insight['total_reviews']}")
```

--------------------------------

### Instantiate and Use Google Gemini Models

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Demonstrates how to instantiate and use various Google Gemini models, including a generic interface. Ensure the GOOGLE_API_KEY environment variable is set.

```python
from fence.models.gemini import (
    Gemini1_5_Pro,
    GeminiFlash1_5,
    GeminiFlash2_0,
    Gemini2_5_Pro,
    Gemini2_5_Flash,
    Gemini2_5_FlashLite,
    Gemini  # Generic interface
)

# Use Gemini models
model = GeminiFlash2_0(source="my_app")

response = model("What are the benefits of renewable energy?")
```

--------------------------------

### Configure OpenAI Model Parameters

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Demonstrates configuring parameters such as temperature, max tokens, and top P for OpenAI models. The API key must be set as an environment variable.

```python
model = GPT4o(
    source="my_app",
    temperature=0.7,
    max_tokens=1000,
    top_p=0.9
)
```

--------------------------------

### Create and Run a Link with a Parser

Source: https://github.com/wouterdurnez/fence/blob/main/docs/LINKS_AND_CHAINS.md

Instantiates a Link with a model, string template, and a BoolParser for structured boolean output.

```python
from fence.links import Link
from fence.templates.string import StringTemplate
from fence.parsers import BoolParser
from fence.models.bedrock import ClaudeHaiku

# Create a link that returns a boolean
sentiment_link = Link(
    model=ClaudeHaiku(),
    template=StringTemplate("Is this text positive? Answer true or false: {text}"),
    parser=BoolParser(),
    name='sentiment_analyzer'
)

# Run it
result = sentiment_link.run(text="I love this product!")
print(result['state'])  # True
```

--------------------------------

### Initialize language models

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Initializes instances of Claude35Sonnet and GPT4omini models, specifying a source and region for Bedrock.

```python
# Get our model
model = Claude35Sonnet(source='demo_notebook', region='us-east-1')
model = GPT4omini(source='demo_notebook')
```

--------------------------------

### Use Structured Message Templates

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Illustrates how to use structured messages with system prompts and a history of user/assistant turns for any model. This ensures consistent input formatting.

```python
from fence.templates.models import Messages, Message

messages = Messages(
    system="You are a helpful assistant",
    messages=[
        Message(role="user", content="What is AI?"),
        Message(role="assistant", content="AI stands for..."),
        Message(role="user", content="Tell me more")
    ]
)

# Works with any model!
response = model.invoke(messages)
```

--------------------------------

### Discover and List MCP Tools

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MCP.md

Connect to an MCP server to automatically discover and list available tools, their descriptions, and parameters.

```python
mcp_client = MCPClient(
    transport_type="streamable_http",
    url="https://api.example.com/mcp"
)

# Connect to discover tools
mcp_client.connect()

# List available tools
for tool in mcp_client.tools:
    print(f"Tool: {tool.name}")
    print(f"  Description: {tool.description}")
    print(f"  Parameters: {tool.parameters}")
```

--------------------------------

### Instantiate and Use Nova Models with AWS Bedrock

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Shows how to instantiate Amazon's Nova models with optional context window selection. AWS credentials are required.

```python
from fence.models.bedrock import NovaLite, NovaMicro, NovaPro, Nova2Lite

# Amazon's Nova models with optional context window selection
model = NovaPro(
    source="my_app",
    cross_region="eu",
    context_window="300k"  # Optional: "24k" or "300k"
)

response = model("What's the weather like?")
```

--------------------------------

### Run Chain with Complete Input

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Provide all necessary input keys, including those not generated by any link, to successfully execute the chain and retrieve the final output.

```python
# Woops, forgot something! There's no link that generates the 'C' key. We can pass it in though.
result = chain.run(input_dict={"A": "A police officer", "B": "Hopeful", "C": "a dog"})
print(result['state'])
```

```python
Output:
The optimistic police officer, accompanied by his loyal dog, patrolled the neighborhood with a smile, spreading positivity and ensuring the safety of the community.

```

--------------------------------

### Create and Run a Simple Bedrock Agent

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/using_bedrock_agents.ipynb

Instantiate a Bedrock Agent with a compatible model and run a basic interaction. The agent's response includes thought process and final answer.

```python
# Create a model
model = NovaPro(region='us-east-1') # Not out in eu-west-1 yet, our default

# Create an agent
agent = BedrockAgent(model=model)

# Run the agent
response = agent.run('hello!')

print(f"\n\nAgent answer: {response.answer}")
```

--------------------------------

### Basic ReAct Agent with Tool Use

Source: https://github.com/wouterdurnez/fence/blob/main/docs/AGENTS.md

Create a basic ReAct agent that can use tools to perform calculations. Ensure the necessary tools and models are imported.

```python
from fence.agents import Agent
from fence.models.openai import GPT4omini
from fence.tools.math import CalculatorTool

# Create an agent with tools
agent = Agent(
    identifier="math_wizard",
    model=GPT4omini(source="demo"),
    description="An agent that can perform calculations",
    tools=[CalculatorTool()],
    max_iterations=5
)

# Ask it something that requires tool use
result = agent.run("What is 1337 * 42 + 999?")
print(result)
```

--------------------------------

### Create and Use a Basic ChatAgent

Source: https://github.com/wouterdurnez/fence/blob/main/docs/AGENTS.md

Instantiate a ChatAgent with an identifier, model, and profile for basic conversational tasks.

```python
from fence.agents import ChatAgent
from fence.models.openai import GPT4omini

# Create a chat agent
agent = ChatAgent(
    identifier="Assistant",
    model=GPT4omini(source="chat"),
    profile="You are a friendly and helpful assistant with a sense of humor."
)

# Have a conversation
response = agent.run("Tell me a joke about programming")
print(response)
```

--------------------------------

### Generate and Print FAQs from Text

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/structured_output_demo.ipynb

Executes the FAQ generation link with the sample text and desired number of questions. The generated output, including topic and Q&A pairs, is then printed in a formatted manner.

```python
# Generate FAQs from the text
print("🔄 Generating FAQ from text...\n")

result = faq_link.run(text=sample_text, num_questions=5)
faq_output = result["state"]

print("✨ FAQ Generated!\n")
print(f"📚 Topic: {faq_output['topic']}")
print("=" * 80)

for i, qa in enumerate(faq_output["qa_pairs"], 1):
    print(f"\n❓ Question {i}: {qa['question']}")
    print(f"✅ Answer: {qa['answer']}")
    print(f"📝 Context: \"{qa['context']}\"")
    print("-" * 80)
```

--------------------------------

### Initialize and Print MessagesTemplate

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Initializes a MessagesTemplate using system and user messages, then prints its representation. This is for more complex prompt structures.

```python
# You can also use the MessagesTemplates for more complex prompts
messages = Messages(
    system='Respond in a {tone} tone',
    messages= [
        Message(role="user", content="Why is the sky {color}?"),
        # Equivalent to Message(role='user', content=Content(type='text', text='Why is the sky blue?'))
        # But Content can also be an image, etc.
    ]
)
messages_template = MessagesTemplate(
    source=messages
)
print(messages_template)
print(f"\nRendered: {messages_template.render(tone='sarcastic', color='blue')}")
```

--------------------------------

### Configure Google Gemini Model Parameters

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Shows how to configure parameters like temperature and max tokens for Google Gemini models. The API key must be set as an environment variable.

```python
model = GeminiFlash2_0(
    source="my_app",
    temperature=0.8,
    max_tokens=1500
)
```

--------------------------------

### Render StringTemplate with Dictionary and Keyword Arguments

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Demonstrates rendering a string template using both a dictionary and keyword arguments. The input dictionary takes precedence over keyword arguments.

```python
# Render it with a dictionary
print(prompt_template.render({'color': 'blue'}))

# Render it with keyword arguments
print(prompt_template.render(color='red'))

# Input dict takes precedence over keyword arguments
print(prompt_template.render(input_dict={'color': 'blue'}, color='red'))
```

--------------------------------

### Load Sample Text for FAQ Generation

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/structured_output_demo.ipynb

Loads a sample text passage about Düsseldorf to be used as input for the FAQ generation. The code also prints the character count and a preview of the loaded text.

```python
# Sample text about a topic (Düsseldorf)
sample_text = """
Düsseldorf is the capital city of North Rhine-Westphalia, the most populous state 
of Germany. It is the second-largest city in the state after Cologne and the 
sixth-largest city in Germany, with a 2024 population of 618,685. Most of Düsseldorf 
lies on the right bank of the Rhine, and the city has grown together with Neuss, 
Ratingen, Meerbusch, Erkrath and Monheim.

Düsseldorf is the central city of Rhine-Ruhr, the second biggest metropolitan region 
by GDP in the European Union, that stretches from Bonn via Cologne and Düsseldorf 
to the Ruhr.

Düsseldorf began as a small settlement at the mouth of the Düssel River, gaining 
city rights in 1288 after the Battle of Worringen. In the Late Middle Ages and 
Renaissance, it grew into a regional political and cultural centre under the Dukes 
of Berg and later as the capital of the United Duchies of Jülich-Cleves-Berg.

The 17th and 18th centuries saw flourishing arts and architecture, with Düsseldorf 
becoming known for its court culture and early art academy. During the Napoleonic 
era, it was briefly part of the Grand Duchy of Berg before coming under Prussian 
control in 1815, where it industrialised rapidly in the 19th century.

During the 20th century, Düsseldorf developed into one of Germany's most important 
centres for administration, business, and culture. In 1946, it became the capital 
of the newly created state of North Rhine-Westphalia, strengthening its political role.
"""

print(f"📄 Sample text loaded ({len(sample_text)} characters)")
print(f"📝 Preview: {sample_text[:150]}...")
```

--------------------------------

### Configure AWS Bedrock Claude Model Parameters

Source: https://github.com/wouterdurnez/fence/blob/main/docs/MODELS.md

Demonstrates configuring inference parameters like temperature, max tokens, and top P for Claude models on AWS Bedrock. Also shows how to return only the text response.

```python
from fence.models.bedrock import Claude35Sonnet

model = Claude35Sonnet(
    source="my_feature",
    region="us-east-1",
    cross_region="us",  # Cross-region inference
    inferenceConfig={
        "temperature": 0.7,
        "maxTokens": 2000,
        "topP": 0.9,
    },
    full_response=False  # Return just the text, not full API response
)
```

--------------------------------

### Initialize and Print Link

Source: https://github.com/wouterdurnez/fence/blob/main/notebooks/basic_usage.ipynb

Initializes a Link object, which combines a prompt template and a model. The link represents an atomic component of LLM interaction.

```python
# The simplest link is the Link class, which just takes a prompt template and a model
link = Link(template=prompt_template, model=model)
print(link)
```
Tokens:
Raw