Norns Knowledge Domain

General knowledge and information retrieval capabilities for the Norns agent system.

Overview

The Knowledge domain provides Norns with the ability to answer general knowledge queries, including weather conditions, news articles, current events, sports scores, and factual information. It integrates with external APIs to retrieve up-to-date information beyond the agent's training data.

Property	Value
Domain	`Domain.KNOWLEDGE`
Supervisor	`KnowledgeDomainSupervisor`
Workers	WebSearchWorker, WeatherWorker, NewsWorker
Level	2 (Domain Supervisor)

Architecture

The Knowledge domain follows the hierarchical agent architecture with a domain supervisor coordinating three specialized workers:

┌─────────────────────────────────────────────────────────┐
│            KNOWLEDGE DOMAIN SUPERVISOR                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ WebSearch    │  │   Weather    │  │    News      │  │
│  │   Worker     │  │   Worker     │  │   Worker     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│         │                  │                 │          │
│         ▼                  ▼                 ▼          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Tavily API   │  │ OpenWeather  │  │ Brave Search │  │
│  │  (Search)    │  │     API      │  │     API      │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘

Query Routing

The supervisor analyzes incoming requests and routes them to the appropriate worker based on intent:

Query Type	Example	Worker
Weather conditions	"What's the weather like?"	WeatherWorker
Weather forecasts	"Will it rain tomorrow?"	WeatherWorker
General facts	"What is the capital of France?"	WebSearchWorker
How-to questions	"How do I make pasta?"	WebSearchWorker
Trivia	"Who won the Super Bowl?"	WebSearchWorker
News articles	"Latest news about AI"	NewsWorker
Sports scores	"NFL scores today"	NewsWorker

Workers

WebSearchWorker

Handles general web search and factual queries using the Tavily API.

Capabilities:

General facts and trivia (who, what, when, where, why questions)
How-to guides and tutorials
Current information about topics
Answers to specific questions

Parameters:

query: Search query (required)
search_depth: "basic" for quick answers, "advanced" for thorough research
max_results: Number of results to return (1-10, default: 5)

Example Queries:

"What is quantum computing?"
"How do I change a tire?"
"Who invented the telephone?"
"When was the Eiffel Tower built?"

WeatherWorker

Retrieves weather conditions and forecasts using OpenWeatherMap API.

Capabilities:

Current weather conditions
5-day weather forecasts
Temperature, humidity, wind speed
Weather descriptions (cloudy, rainy, etc.)

Parameters:

location: City name or "current" for default location
units: "imperial" (Fahrenheit) or "metric" (Celsius)
forecast_type: "current" or "forecast"

Example Queries:

"What's the weather like?"
"Weather in Austin, Texas"
"Will it rain tomorrow?"
"Is it going to snow this week?"
"Temperature in San Francisco"

Note: If location is "current", "here", "home", or blank, the system uses the DEFAULT_LOCATION environment variable.

NewsWorker

Searches for recent news articles using the Brave Search News API.

Capabilities:

Current events and breaking news
Sports scores and results
Recent headlines on any topic
Time-filtered news (day, week, month)

Parameters:

query: News topic to search for (required)
count: Number of results (1-10, default: 5)
freshness: "day", "week", or "month"

Example Queries:

"Latest news about artificial intelligence"
"NFL scores today"
"What happened in tech news?"
"Breaking news about climate"

Setup

Required API Keys

All API keys must be configured in /Users/ravenhelm/ravenhelm/secrets/.env:

# Tavily API (Web Search)
TAVILY_API_KEY=tvly-...

# OpenWeatherMap API (Weather)
OPENWEATHER_API_KEY=...

# Brave Search API (News)
BRAVE_API_KEY=...

# Default location for weather queries (optional)
DEFAULT_LOCATION=San Marcos, TX

API Service Setup

1. Tavily API (Web Search)

Sign up: https://tavily.com

Free Tier:

1,000 searches/month
Basic and advanced search depth
Real-time web results

Steps:

Create account at https://tavily.com
Navigate to API Keys section
Copy API key (starts with tvly-)
Add to .env as TAVILY_API_KEY

2. OpenWeatherMap API (Weather)

Sign up: https://openweathermap.org/api

Free Tier:

1,000 calls/day
Current weather data
5-day forecast
3-hour forecast intervals

Steps:

Create account at https://openweathermap.org/api
Subscribe to "Current Weather Data" and "5 Day Forecast" (both free)
Go to API Keys section
Copy or generate API key
Add to .env as OPENWEATHER_API_KEY

Warning: API keys can take up to 2 hours to activate after signup.

3. Brave Search API (News)

Sign up: https://brave.com/search/api/

Free Tier:

2,000 queries/month
News search with freshness filters
No credit card required

Steps:

Create account at https://brave.com/search/api/
Navigate to API Keys section
Generate new API key
Add to .env as BRAVE_API_KEY

Docker Configuration

Ensure environment variables are passed to the norns-agent container in docker-compose.yml:

norns-agent:
  environment:
    # Knowledge Domain APIs
    - TAVILY_API_KEY=${TAVILY_API_KEY}
    - OPENWEATHER_API_KEY=${OPENWEATHER_API_KEY}
    - BRAVE_API_KEY=${BRAVE_API_KEY}
    - DEFAULT_LOCATION=${DEFAULT_LOCATION:-San Marcos, TX}

Restart After Configuration

# Restart Norns agent to load new environment variables
ssh ravenhelm@100.115.101.81 "docker restart norns-agent"

# Verify logs
ssh ravenhelm@100.115.101.81 "docker logs -f norns-agent"

Usage Examples

Weather Queries

User: What's the weather like?
Norns: [Routes to WeatherWorker with location="current"]
→ Provides current weather for DEFAULT_LOCATION

User: Weather in Austin
Norns: [Routes to WeatherWorker with location="Austin, TX"]
→ Provides current weather for Austin

User: Will it rain tomorrow in Seattle?
Norns: [Routes to WeatherWorker with forecast_type="forecast"]
→ Provides 5-day forecast and analyzes rain probability

Web Search Queries

User: What is machine learning?
Norns: [Routes to WebSearchWorker with search_depth="basic"]
→ Returns concise definition and overview

User: How do I bake sourdough bread?
Norns: [Routes to WebSearchWorker with search_depth="advanced"]
→ Returns detailed step-by-step instructions

User: Who won the 2024 World Series?
Norns: [Routes to WebSearchWorker]
→ Returns current sports information

News Queries

User: Latest AI news
Norns: [Routes to NewsWorker with query="artificial intelligence", freshness="week"]
→ Returns recent AI-related news articles

User: NFL scores today
Norns: [Routes to NewsWorker with query="NFL scores", freshness="day"]
→ Returns today's NFL game results

User: What's happening in tech?
Norns: [Routes to NewsWorker with query="technology news", freshness="week"]
→ Returns recent tech headlines

Implementation Details

File Locations

/Users/ravenhelm/ravenhelm/docs/AI-ML-Platform/norns-agent/agent/
├── agents/
│   ├── domain_supervisors/
│   │   └── knowledge_supervisor.py    # Domain supervisor
│   └── workers/
│       └── knowledge_workers.py        # Worker implementations
└── tools.py                            # Tool function definitions

Code Structure

Domain Supervisor (knowledge_supervisor.py):

Analyzes user intent using LLM
Routes to appropriate worker
Extracts and passes parameters
Aggregates results

Workers (knowledge_workers.py):

WebSearchWorker: Tavily API integration
WeatherWorker: OpenWeatherMap API integration
NewsWorker: Brave Search News API integration

Tools (tools.py):

web_search(): Async Tavily search function
get_weather(): Async weather data retrieval
search_news(): Async news search function

Event Publishing

All workers publish events to Redpanda for observability:

TOOL_CALL event when worker starts
TOOL_RESULT event when worker completes
Includes execution time and metadata

Events can be traced in Langfuse for debugging.

Troubleshooting

Issue: "Web search is not configured"

Symptoms: Worker returns configuration error message

Cause: TAVILY_API_KEY not set or not loaded

Solution:

# Check environment variable
ssh ravenhelm@100.115.101.81 "docker exec norns-agent env | grep TAVILY"

# Verify .env file
ssh ravenhelm@100.115.101.81 "grep TAVILY /Users/ravenhelm/ravenhelm/secrets/.env"

# Restart container
ssh ravenhelm@100.115.101.81 "docker restart norns-agent"

Issue: "Weather service is not configured"

Symptoms: Weather queries return configuration error

Cause: OPENWEATHER_API_KEY not set or API key not activated

Solution:

# Check if key is set
ssh ravenhelm@100.115.101.81 "docker exec norns-agent env | grep OPENWEATHER"

# Test manually
curl "https://api.openweathermap.org/data/2.5/weather?q=Austin&appid=YOUR_KEY"

# Restart container
ssh ravenhelm@100.115.101.81 "docker restart norns-agent"

Issue: "News search is not configured"

Symptoms: News queries fail with configuration error

Cause: BRAVE_API_KEY not set

Solution:

# Check environment variable
ssh ravenhelm@100.115.101.81 "docker exec norns-agent env | grep BRAVE"

# Verify .env file
ssh ravenhelm@100.115.101.81 "grep BRAVE /Users/ravenhelm/ravenhelm/secrets/.env"

# Restart container
ssh ravenhelm@100.115.101.81 "docker restart norns-agent"

Issue: Weather returns wrong location

Symptoms: Weather queries always return data for unexpected location

Cause: DEFAULT_LOCATION environment variable set incorrectly

Solution:

# Check current default location
ssh ravenhelm@100.115.101.81 "docker exec norns-agent env | grep DEFAULT_LOCATION"

# Update in .env file
ssh ravenhelm@100.115.101.81 "nano /Users/ravenhelm/ravenhelm/secrets/.env"
# Set: DEFAULT_LOCATION=YourCity, YourState

# Restart
ssh ravenhelm@100.115.101.81 "docker restart norns-agent"

Issue: API rate limit exceeded

Symptoms: Errors about quota or rate limits

Solutions:

Tavily (1,000/month):

Monitor usage at https://tavily.com/dashboard
Consider upgrading plan if needed
Use search_depth="basic" to reduce quota usage

OpenWeatherMap (1,000/day):

Check usage at https://openweathermap.org/price
Free tier is generous for most use cases
Upgrade to paid plan if needed

Brave Search (2,000/month):

Monitor at https://brave.com/search/api/
Upgrade to paid tier for higher limits

Debugging with Langfuse

View detailed trace data for Knowledge domain queries:

Open https://langfuse.ravenhelm.dev
Navigate to Traces
Filter by session ID or user ID
Look for TOOL_CALL and TOOL_RESULT events
Check execution time and error messages

# View recent logs for errors
ssh ravenhelm@100.115.101.81 "docker logs norns-agent 2>&1 | grep -A 10 'knowledge'"

Future Enhancements

Potential additions to the Knowledge domain:

Calculator/Math: Wolfram Alpha integration for calculations
Wikipedia: Direct Wikipedia API for encyclopedic knowledge
Stock/Finance: Real-time stock prices and financial data
Translation: Language translation capabilities
Image Search: Visual search capabilities
Maps/Directions: Location and navigation data

Norns Agent - Core agent architecture
AI/ML Platform - Platform overview
Norns Memory System - Memory architecture
Langfuse - Observability and tracing

Overview​

Architecture​

Query Routing​

Workers​

WebSearchWorker​

WeatherWorker​

NewsWorker​

Setup​

Required API Keys​

API Service Setup​

1. Tavily API (Web Search)​

2. OpenWeatherMap API (Weather)​

3. Brave Search API (News)​

Docker Configuration​

Restart After Configuration​

Usage Examples​

Weather Queries​

Web Search Queries​

News Queries​

Implementation Details​

File Locations​

Code Structure​

Event Publishing​

Troubleshooting​

Issue: "Web search is not configured"​

Issue: "Weather service is not configured"​

Issue: "News search is not configured"​

Issue: Weather returns wrong location​

Issue: API rate limit exceeded​

Debugging with Langfuse​

Future Enhancements​

Related Documentation​

Overview

Architecture

Query Routing

Workers

WebSearchWorker

WeatherWorker

NewsWorker

Setup

Required API Keys

API Service Setup

1. Tavily API (Web Search)

2. OpenWeatherMap API (Weather)

3. Brave Search API (News)

Docker Configuration

Restart After Configuration

Usage Examples

Weather Queries

Web Search Queries

News Queries

Implementation Details

File Locations

Code Structure

Event Publishing

Troubleshooting

Issue: "Web search is not configured"

Issue: "Weather service is not configured"

Issue: "News search is not configured"

Issue: Weather returns wrong location

Issue: API rate limit exceeded

Debugging with Langfuse

Future Enhancements

Related Documentation