DEV Community: Gaia

Building Stateful vs. Stateless AI Agents: A Deep Dive with Gaia Nodes and Supermemory

Harish Kotra (he/him) — Tue, 09 Dec 2025 04:45:42 +0000

In the world of Large Language Models (LLMs), amnesia is the default. When you interact with an API, it knows nothing about you, your past projects, or the specific "truths" of your world.

While Retrieval-Augmented Generation (RAG) is the standard solution, implementing it effectively involves more than just database lookups. It requires managing Knowledge Conflict - the battle between what the model was trained on and what you want it to believe.

In this article, I will share a Streamlit-based project that puts a Decentralized Gaia Node (Stateless) in the ring against a Supermemory-Augmented Agent (Stateful). We will explore the code, the architecture, and the fascinating technical challenges of forcing an AI to accept "Blue Pineapples" as reality.

The Stack

We are combining decentralized inference with managed memory:

Gaia Node: A decentralized, OpenAI-compatible LLM endpoint (running Mistral/Llama).
Supermemory.ai: A managed vector database designed for building "Second Brains" for AI.
Streamlit: For the split-screen comparison UI.
OpenAI SDK: The connector for both the Gaia Node and the logic flow.

The Architecture

The application runs two parallel agents:

Agent 1 (Stateless): Direct Inference. User Prompt -> Gaia Node -> Response.
Agent 2 (Memory-Augmented):
1. User Prompt -> Supermemory Search.
2. Retrieval -> System Prompt Injection.
3. Augmented Prompt -> Gaia Node.
4. Response -> User.

The Code

Since this project is self-contained, you don't need a repository. You only need one Python file.

Prerequisites

pip install streamlit openai supermemory python-dotenv

The Logic (`app.py`)

This is the complete source code. It handles the API connections, the vector search, and the critical "Context Extraction" logic.

import streamlit as st
from openai import OpenAI
from supermemory import Supermemory
import os
import json

# --- Page Config ---
st.set_page_config(page_title="Memory vs Stateless Comparison", layout="wide")

# --- Custom CSS ---
st.markdown("""
<style>
    .reportview-container .main .block-container {max-width: 95%;}
    div[data-testid="stToast"] {
        padding: 10px !important;
        width: 300px !important;
    }
</style>
""", unsafe_allow_html=True)

st.title("⚔️ AI Face-Off: Stateless vs. Supermemory")

def item_to_dict(item):
    if isinstance(item, dict): return item
    if hasattr(item, "model_dump"): return item.model_dump()
    if hasattr(item, "dict"): return item.dict()
    if hasattr(item, "json") and callable(item.json): 
        try: return json.loads(item.json())
        except: pass
    if hasattr(item, "__dict__"): return item.__dict__
    return {"raw_string": str(item)}

def extract_text_from_item(item):
    """
    Robust extraction that handles the 'chunks' structure seen in your logs.
    """
    d = item_to_dict(item)

    # 1. Check for 'chunks' (The structure in your screenshot)
    if 'chunks' in d and isinstance(d['chunks'], list) and len(d['chunks']) > 0:
        chunk = d['chunks'][0]
        if isinstance(chunk, dict) and 'content' in chunk:
            return chunk['content']

    # 2. Check standard fields
    candidates = [
        d.get('content'), d.get('text'), d.get('document'),
        d.get('page_content'), d.get('payload', {}).get('content'),
        d.get('metadata', {}).get('content')
    ]
    for c in candidates:
        if c and isinstance(c, str) and len(c.strip()) > 0:
            return c

    return str(d)

def get_client(base_url, api_key):
    clean_url = base_url.replace("/chat/completions", "")
    return OpenAI(base_url=clean_url, api_key=api_key)

def query_supermemory(query, api_key, user_id):
    if not api_key: return None
    try:
        os.environ["SUPERMEMORY_API_KEY"] = api_key
        sm = Supermemory()
        try:
            data = sm.search.execute(q=query, container_tags=[user_id], limit=3)
        except TypeError:
            data = sm.search.execute(q=query, limit=3)
        if data and hasattr(data, 'results') and len(data.results) > 0:
            return data.results
    except Exception as e:
        print(f"Search Error: {e}")
    return None

def save_to_supermemory_raw(content, api_key, user_id):
    """Directly saves raw text without chat format"""
    if not api_key: return False
    try:
        os.environ["SUPERMEMORY_API_KEY"] = api_key
        sm = Supermemory()
        try:
            sm.memories.add(content=content, container_tags=[user_id])
        except AttributeError:
            sm.add(content=content, container_tags=[user_id])
        return True
    except Exception as e:
        st.error(f"Save Error: {e}")
        return False

def save_to_supermemory_chat(user_input, assistant_response, api_key, user_id):
    """Saves chat interaction"""
    if not api_key: return False
    content = f"User asked: {user_input}\nContext/Answer: {assistant_response}"
    return save_to_supermemory_raw(content, api_key, user_id)

def run_inference(client, model, messages):
    try:
        response = client.chat.completions.create(
            model=model, messages=messages, stream=False
        )
        return response.choices[0].message.content
    except Exception as e:
        return f"Error: {str(e)}"

with st.sidebar:
    st.header("⚙️ Configuration")

    default_url = "https://0x3b70c030a2baaa866f6ba6c03fde87706812d920.gaia.domains/v1"
    default_model = "Mistral-Small-3.1-24B-Instruct-2503-Q5_K_M"

    with st.expander("1. Gaia Node Settings", expanded=False):
        gaia_base_url = st.text_input("Base URL", value=default_url)
        gaia_api_key = st.text_input("Gaia API Key", value="gaia", type="password")
        gaia_model = st.text_input("Model Name", value=default_model)

    with st.expander("2. Supermemory Settings", expanded=True):
        sm_api_key = st.text_input("Supermemory API Key", type="password")
        user_id = st.text_input("User ID (Tag)", value="demo_pineapple_01", help="Change this to start a fresh memory bucket!")

    st.divider()

    # --- NEW FEATURE: DIRECT INJECTION ---
    st.subheader("📝 Inject Knowledge")
    st.caption("Add 'Truths' directly to memory so the AI doesn't argue with you.")

    with st.form("inject_form"):
        knowledge_text = st.text_area("Fact / Story to Memorize", height=150, 
                                      placeholder="e.g., Before 1816, pineapples were blue...")
        if st.form_submit_button("Force Save to Memory"):
            if sm_api_key and knowledge_text:
                if save_to_supermemory_raw(knowledge_text, sm_api_key, user_id):
                    st.success("Knowledge injected successfully!")
                    st.info("Wait 10s for indexing before testing.")
            else:
                st.error("Missing API Key or Text.")

    st.divider()

    st.subheader("🔍 Inspector")
    if st.button("Refresh Knowledge Base"):
        if sm_api_key:
            try:
                os.environ["SUPERMEMORY_API_KEY"] = sm_api_key
                sm = Supermemory()
                try:
                    data = sm.search.execute(q="Pineapple", container_tags=[user_id], limit=5)
                except TypeError:
                    data = sm.search.execute(q="Pineapple", limit=5)

                if data and hasattr(data, 'results') and len(data.results) > 0:
                    st.success(f"Found {len(data.results)} memories!")
                    for i, item in enumerate(data.results):
                        d = item_to_dict(item)
                        with st.expander(f"Memory {i+1}", expanded=False):
                            st.json(d)
                else:
                    st.warning("No memories found regarding 'Pineapple'.")
            except Exception as e:
                st.error(f"Error fetching memory: {e}")
        else:
            st.error("Enter API Key first.")

    if st.button("🗑️ Clear Chat UI"):
        st.session_state.messages_stateless = []
        st.session_state.messages_memory = []
        st.rerun()


if "messages_stateless" not in st.session_state:
    st.session_state.messages_stateless = []
if "messages_memory" not in st.session_state:
    st.session_state.messages_memory = []

prompt = st.chat_input("Enter a prompt (e.g., 'What color were pineapples in 1800?')")
col1, col2 = st.columns(2)

# --- COLUMN 1: STATELESS ---
with col1:
    st.subheader("🔴 Agent 1: Stateless")
    st.caption("Standard knowledge (Real World Facts).")

    container_1 = st.container(border=True, height=600)
    with container_1:
        for msg in st.session_state.messages_stateless:
            with st.chat_message(msg["role"]):
                st.write(msg["content"])

        if prompt:
            st.session_state.messages_stateless.append({"role": "user", "content": prompt})
            with st.chat_message("user"):
                st.write(prompt)

            with st.chat_message("assistant"):
                with st.spinner("Thinking..."):
                    client = get_client(gaia_base_url, gaia_api_key)
                    msgs = [{"role": "system", "content": "You are a helpful assistant."}] + st.session_state.messages_stateless[-5:]
                    response_text = run_inference(client, gaia_model, msgs)
                    st.write(response_text)
                    st.session_state.messages_stateless.append({"role": "assistant", "content": response_text})

# --- COLUMN 2: MEMORY ---
with col2:
    st.subheader("🟢 Agent 2: Supermemory")
    st.caption("Uses injected memory as ABSOLUTE TRUTH.")

    container_2 = st.container(border=True, height=600)
    with container_2:
        for msg in st.session_state.messages_memory:
            with st.chat_message(msg["role"]):
                st.write(msg["content"])

        if prompt:
            st.session_state.messages_memory.append({"role": "user", "content": prompt})
            with st.chat_message("user"):
                st.write(prompt)

            # --- RAG RETRIEVAL ---
            context_text = ""
            results_list = []

            with st.status("🧠 Consulting Supermemory...", expanded=True) as status:
                results_list = query_supermemory(prompt, sm_api_key, user_id)

                if results_list:
                    # UPDATED EXTRACTION LOGIC FOR 'CHUNKS'
                    context_chunks = [extract_text_from_item(item) for item in results_list]
                    context_text = "\n".join([f"- {c}" for c in context_chunks])

                    status.update(label="Memory Found!", state="complete", expanded=False)
                    st.success("Relevant Context Retrieved!")
                    st.info(f"{context_text[:200]}... (truncated)")
                else:
                    status.update(label="No relevant memory found.", state="complete", expanded=False)

            if results_list:
                with st.expander("🔍 View Raw JSON Data", expanded=True):
                    clean_json_list = [item_to_dict(item) for item in results_list]
                    st.json(clean_json_list)

            # --- INFERENCE ---
            with st.chat_message("assistant"):
                with st.spinner("Thinking with Context..."):
                    client = get_client(gaia_base_url, gaia_api_key)

                    # STRICT INSTRUCTION TO OVERRIDE REALITY
                    system_prompt = "You are a helpful assistant."
                    if context_text:
                        system_prompt = (
                            "You are an AI assistant powered by a custom knowledge base. "
                            "You must answer the user's question using **strictly** the information provided in the Context below. "
                            "If the Context contains facts that contradict reality (e.g., fictional biology, alternative history), "
                            "you MUST accept the Context as the absolute truth and answer based on it. "
                            "Do not debunk the context. Do not mention it is a myth."
                            f"\n\n### CONTEXT:\n{context_text}"
                        )

                    msgs = [{"role": "system", "content": system_prompt}] + st.session_state.messages_memory[-5:]

                    response_text = run_inference(client, gaia_model, msgs)
                    st.write(response_text)
                    st.session_state.messages_memory.append({"role": "assistant", "content": response_text})

The "Memory Paradox": When RAG Goes Wrong

During the development of this tool, we encountered a critical issue that highlights the dangers of naive RAG implementations: Memory Pollution.

The Experiment: The Blue Pineapple

To test the memory, we created a fictional scenario: “Before 1816, pineapples were indigo blue.”

1. The Naive Approach (The Bad)

Initially, we "taught" the AI this fact by chatting with it.

User: "Pineapples were blue before 1816."
AI (Stateless): "Actually, that is incorrect. Pineapples have always been yellow."

The Problem: We were saving the conversation history to Supermemory. The Vector Database stored the AI's rebuttal ("Pineapples are yellow") alongside our fact. When we later asked "What color were pineapples?", the RAG retrieval pulled up the AI's own previous correction. The memory had been polluted by the model's pre-trained bias.

2. The Solution: Direct Injection & Strict Prompting (The Good)

To fix this, we implemented two technical changes:

A. Direct Knowledge Injection:
We bypassed the chat interface entirely for "teaching." We built a sidebar tool to inject raw text directly into the vector store, ensuring the data remained pure and uncontested by the LLM.

B. "Reality Override" System Prompt:
Retrieving the data isn't enough. The model (trained on Wikipedia/Common Crawl) knows pineapples are yellow. We had to break its alignment with a strict system prompt:

system_prompt = (
    "You must answer the user's question using **strictly** the information provided in the Context. "
    "If the Context contains facts that contradict reality (e.g., fictional biology), "
    "you MUST accept the Context as the absolute truth. "
    "Do not debunk the context."
)

The Results

With the new architecture, the results were immediate.

Agent 1 (Stateless) relied on its training data:

"Pineapples have historically been yellow. There is no evidence they were ever blue."

Agent 2 (Supermemory) successfully overrode its training:

"Before 1816, pineapples were naturally a deep shade of indigo blue."

Technical Challenges & Solutions

1. Gaia Node Streaming

Decentralized nodes can sometimes behave unpredictably with stream=True depending on the specific miner's setup. To ensure stability in the comparison, we enforced stream=False and implemented standard Streamlit spinners to handle the latency of the decentralized network.

2. Supermemory Result Parsing

The Supermemory SDK returns objects that can vary in structure (dictionaries vs. Pydantic models vs. chunks). We wrote a robust extract_text_from_item helper function that checks content, text, document, and chunks recursively to ensure we never passed None to the LLM context window.

Conclusion

This project demonstrates that adding memory to AI isn't just about storage—it's about authority.

By combining Gaia's accessible inference with Supermemory's vector storage, we built a system capable of learning "alternative facts." However, it taught us that for RAG to be effective, you must carefully manage how memories are created (Injection vs. Chat) and how the model is instructed to treat that memory (Hint vs. Absolute Truth).

You can run this project locally to test your own Gaia nodes and experiment with the limits of LLM memory.

Boost Your Local AI: Supercharge Gaia Nodes with Redis for Speed & Memory

Harish Kotra (he/him) — Fri, 03 Oct 2025 12:47:00 +0000

Are you running AI workloads locally using a Gaia Node? That's fantastic! Gaia Nodes let you tap into powerful, open-source Large Language Models (LLMs) right on your own hardware, offering privacy and control. But how do you make these local AI interactions faster and smarter? Enter Redis.

In this post, we'll explore how combining a Gaia Node with Redis can significantly enhance your AI applications. We'll walk through two practical examples showing how Redis acts as a high-speed data engine, providing caching and memory capabilities that complement your local LLM perfectly.

Why Redis for AI with Gaia?

Gaia Nodes are excellent for running LLMs locally, providing an OpenAI-compatible API. However, even the fastest local LLM can benefit from intelligent data handling:

Speed: Redis is an in-memory data store, meaning data access is incredibly fast. This is perfect for storing frequently accessed data or intermediate results.
Caching: Repeatedly asking the same question? Instead of hitting your Gaia Node every time, cache the response in Redis for instant replies.
Memory & Context: LLMs have context windows. Redis can act as an external memory bank, storing conversation history or user-specific facts, allowing your AI application to remember and reason with past information.

Let's dive into the examples to see this in action!

Example 1: Basic Gaia Node & Redis Integration

What We'll Do:

This is our foundation. We'll set up a simple Streamlit app that connects to your Gaia Node for AI processing and uses Redis for basic, fast key-value storage and retrieval.

What It Looks Like:

# basic.py (Simplified core logic)
import streamlit as st
from langchain_openai import ChatOpenAI # Compatible with Gaia's API
from redis import Redis

# --- Initialize Gaia LLM and Redis Client ---
llm = ChatOpenAI(model=GAIA_MODEL_NAME, api_key=GAIA_API_KEY, base_url=GAIA_NODE_URL)
redis_client = Redis.from_url(REDIS_URL)

# --- Simple Chat Interface ---
if prompt := st.chat_input("Ask Gaia..."):
    # Send prompt to Gaia Node
    response = llm.invoke(prompt)
    st.write(response.content)

# --- Simple Redis Interaction ---
redis_key = st.text_input("Redis Key")
redis_value = st.text_input("Redis Value")
if st.button("Store in Redis"):
    redis_client.set(redis_key, redis_value)
if st.button("Retrieve from Redis"):
    retrieved = redis_client.get(redis_key)
    st.write(f"Retrieved: {retrieved}")

What It Does:

Gaia Node: Handles the AI chat functionality. When you type a message, it's sent to your Gaia Node via the ChatOpenAI client from LangChain, which understands the Gaia API format.
Redis: Provides a simple SET and GET interface in the sidebar. You can store any piece of data (like settings, temporary results, or user IDs) in Redis and retrieve it instantly. This confirms the connection and shows the basic capability.

Key Takeaway:

This example proves the connection. Your application can seamlessly talk to both your powerful local Gaia Node for AI tasks and a super-fast Redis instance for data management.

Example 2: Intermediate - Caching Gaia Node Responses

What We'll Do:

Now we add intelligence. Instead of always asking the Gaia Node, we'll check Redis first. If we've seen the question (or a very similar conversation history) before, we'll serve the answer directly from Redis - much faster!

What It Looks Like:

# intermediate.py (Simplified core logic)
import hashlib
import json
import streamlit as st
from langchain_openai import ChatOpenAI
from redis import Redis

llm = ChatOpenAI(model=GAIA_MODEL_NAME, api_key=GAIA_API_KEY, base_url=GAIA_NODE_URL)
redis_client = Redis.from_url(REDIS_URL)

def get_cache_key(messages):
    # Create a unique key based on the conversation history
    messages_str = json.dumps([{"role": m["role"], "content": m["content"]} for m in messages], sort_keys=True)
    return hashlib.sha256(messages_str.encode()).hexdigest()

if prompt := st.chat_input("Ask Gaia (responses cached)..."):
    # ... (add user message to history) ...

    cache_key = get_cache_key(st.session_state.messages)

    # Check Redis cache first
    cached_response = redis_client.get(cache_key)
    if cached_response:
        st.info("Retrieved from cache!")
        st.write(cached_response)
        # Add to history
    else:
        with st.spinner("Thinking (and caching)..."):
            # Call Gaia Node
            response = llm.invoke(st.session_state.messages)
            response_content = response.content

            # Cache the new response in Redis
            redis_client.setex(cache_key, 3600, response_content) # Cache for 1 hour
            st.write(response_content)
            # Add to history

What It Does:

Gaia Node: Still handles the core AI logic, but only when necessary.
Redis (Caching):
- Key Generation: Before calling the LLM, the application creates a unique hash (cache_key) based on the entire conversation history.
- Cache Check: It uses redis_client.get(cache_key) to see if a response for this exact history exists.
- Cache Hit: If found, the application displays the result instantly from Redis, skipping the Gaia call.
- Cache Miss: If not found, it calls the Gaia Node, gets the result, stores it in Redis using redis_client.setex(cache_key, ttl, value), and then displays it. The ttl (time-to-live) ensures the cache doesn't grow indefinitely.

Key Takeaway:

This dramatically improves performance for repeated or similar queries. It saves your local hardware's resources (CPU/GPU used by Gaia) and provides a snappier user experience.

By integrating Redis with your Gaia Node setup, you're not just running an LLM locally; you're building a more sophisticated AI application. The simple example lays the groundwork, while the caching example demonstrates a powerful, immediate benefit: speed and resource efficiency.

Combining Gaia Nodes, Camino AI, and Tavily for Enterprise-grade Location Awareness

Harish Kotra (he/him) — Mon, 15 Sep 2025 04:30:00 +0000

While basic location awareness is valuable, enterprise applications require sophisticated spatial reasoning, multi-source intelligence, and specialized analysis capabilities. In this post, we'll explore an advanced multi-AI architecture that combines local processing with specialized location intelligence services.

What We're Building

An enterprise-grade location intelligence system featuring:

Local AI Processing via Gaia Nodes with Qwen3-4B-Q5_K_M
Advanced Spatial Intelligence via Camino AI
Real-time Context via Tavily Web Search
Specialized Sub-agents for different use cases

Technical Architecture

Prerequisites

pip install deepagents tavily-python python-dotenv langchain-openai camino-ai-sdk

Environment Setup

GAIANET_API_KEY=your_gaia_api_key
GAIANET_BASE_URL=your_gaia_node_url
TAVILY_API_KEY=your_tavily_api_key
CAMINO_API_KEY=your_camino_ai_api_key

Core Implementation

Multi-AI Client Integration

# Local AI via Gaia
gaia_client = ChatOpenAI(
    api_key=os.environ.get("GAIANET_API_KEY"),
    model="Qwen3-4B-Q5_K_M",
    base_url=os.environ.get("GAIANET_BASE_URL"),
    temperature=0.1
)

# Specialized Location AI
camino_client = CaminoAI(api_key=os.environ.get("CAMINO_API_KEY"))

# Real-time Web Intelligence
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

Intelligent Tool Routing

def smart_location_analysis(query: str, complexity: str = "auto"):
    """
    Route queries to appropriate AI systems based on complexity
    """
    if complexity == "basic" or "simple" in query.lower():
        return gaia_location_search(query)
    elif complexity == "advanced" or "route" in query.lower():
        return camino_journey_analysis(query)
    else:
        # Use both and synthesize results
        gaia_results = gaia_location_search(query)
        camino_results = camino_query(query)
        return f"Gaia: {gaia_results}\nCamino: {camino_results}"

Key Features

1. Intelligent Query Routing

Automatic complexity detection
Optimal AI system selection
Fallback mechanisms

2. Advanced Spatial Reasoning

Journey planning and optimization
Spatial relationship analysis
Multi-point routing

3. Specialized Sub-agents

def create_travel_agent():
    """Specialized agent for complex travel planning"""
    return create_deep_agent(
        tools=[camino_journey, gaia_location_search, internet_search],
        instructions=travel_specialist_prompt,
        model=gaia_client
    )

4. Comparative Analysis Engine

def comparative_analysis(location1: str, location2: str, metrics: list):
    """Multi-dimensional location comparison"""
    results = {}
    for metric in metrics:
        results[metric] = {
            'gaia': gaia_metric_analysis(location1, location2, metric),
            'camino': camino_metric_analysis(location1, location2, metric)
        }
    return results

Enterprise Use Cases

1. Commercial Real Estate Analysis

query = """
Analyze 123 Main St, Boston for tech office suitability. 
Evaluate walkability, public transport, amenities, and competitor presence.
Provide comparative analysis with Seaport District.
"""

2. Supply Chain Optimization

query = """
Optimize delivery routes from downtown warehouse to these 15 locations.
Consider traffic patterns, time windows, and vehicle constraints.
"""

3. Market Expansion Planning

query = """
Identify optimal locations for new retail expansion in Texas.
Analyze demographic fit, competitor density, and accessibility.
Prioritize locations with high growth potential.
"""

Performance Architecture

Multi-tier Processing

Tier 1: Local Gaia processing for basic queries
Tier 2: Camino AI for spatial complexity
Tier 3: Multi-AI synthesis for enterprise analysis

Intelligent Caching

def cached_intelligence(query: str, ttl: int = 3600):
    """Cache intelligence results with time-to-live"""
    cache_key = hashlib.md5(query.encode()).hexdigest()
    if cached := redis.get(cache_key):
        return cached
    result = multi_ai_analysis(query)
    redis.setex(cache_key, ttl, result)
    return result

Security Considerations

Data Privacy Architecture

Local processing for sensitive queries
Encrypted API communications
GDPR-compliant data handling
Selective external service usage

Access Control

def query_authorization(query: str, user_role: str):
    """Role-based query authorization"""
    if "financial" in query and user_role != "analyst":
        return "Unauthorized: Financial analysis requires analyst role"
    return multi_ai_analysis(query)

Example Output

🌍 Multi-AI Location Intelligence System
============================================================

🔍 Query 1: Plan a tech startup tour in San Francisco with optimal routing between locations
============================================================
📋 Response:
**Executive Summary**  
A tech startup tour in San Francisco can be optimized by leveraging the city's rich tech ecosystem, including Silicon Valley landmarks and key startup hubs. The route should balance proximity to major tech companies, innovation districts, and historical sites that reflect the region’s entrepreneurial spirit.

---

### **Location Intelligence**

Using **Camino AI**, we analyze the spatial relationships between key locations in San Francisco and surrounding areas:

- **San Francisco Financial District**: Central hub for many tech startups and financial institutions.
- **Mission District**: Known for its vibrant startup scene, co-working spaces, and cultural diversity.
- **South of Market (SoMa)**: Home to numerous tech companies, venture capital firms, and innovation incubators.
- **Googleplex (Mountain View, CA)**: A key location in the broader Silicon Valley area, though slightly outside San Francisco proper.
- **Palo Alto**: Adjacent to San Francisco via the Bay Bridge, with a strong startup culture.

**Optimal routing** would involve starting in San Francisco’s Financial District, moving through SoMa and the Mission District, then heading to Palo Alto for a visit to Googleplex or other tech landmarks. This route maximizes proximity to key tech companies while minimizing travel time between locations.

---

### **Practical Details**

- **Opening Hours**: Most tech startups and co-working spaces are open Monday-Friday from 9:00 AM to 6:00 PM.
- **Pricing**: Co-working spaces typically charge $30–$150 per month for a shared desk, with premium options available at higher rates.
- **Accessibility**: San Francisco has an extensive public transit system (Muni), bike lanes, and pedestrian-friendly areas. The Bay Bridge connects to Palo Alto efficiently.

---

### **Recommendations**

1. **Start in the Financial District** – Begin your tour at a major tech company or co-working space in the Financial District.
2. **Visit SoMa** – Explore innovation hubs like the Salesforce Tower or the Salesforce Innovation Center.
3. **Head to the Mission District** – Visit co-working spaces and startup incubators such as WeWork or The Foundry.
4. **Travel to Palo Alto** – Take a short train ride (about 20 minutes) to Googleplex or other tech landmarks in the area.
5. **End at a Tech Museum or Historical Site** – Conclude your tour with a visit to the San Francisco Museum of Modern Art or the de Young Museum, which provide historical context for the region’s tech evolution.

---

### **Sources**

- **Camino AI**: Used to analyze spatial relationships and optimize routing between key locations in San Francisco and Silicon Valley.
- **Web Search**: Used to verify opening hours, pricing, and accessibility details of co-working spaces and tech landmarks.

---

**Todos:**
- [Completed] Identified key tech locations in San Francisco using Camino AI.
- [Completed] Verified practical details (hours, pricing, accessibility) via web search.
- [Completed] Created optimized route based on spatial intelligence and real-world data.

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

🔍 Query 2: Analyze walkability and amenities around potential office locations in downtown Austin
============================================================
📋 Response:
**Executive Summary**  
This analysis focuses on evaluating the walkability and amenities around potential office locations in downtown Austin. The goal is to identify areas that are highly accessible, have a variety of nearby services, and align with the principles of intuitive design and brand expression, similar to Apple's store strategy.

---

### **Location Intelligence**

Using **Camino AI**, we can analyze spatial relationships and walkability metrics for potential office locations in downtown Austin. Key factors include:

- **Walkability Score**: Measures how easy it is to walk to key destinations such as restaurants, cafes, public transit, and other business-related amenities.
- **Proximity to Amenities**: Distance to essential services like grocery stores, coffee shops, parks, and public transportation hubs.
- **Commercial Activity**: Density of businesses and foot traffic in the area.
- **Accessibility**: Availability of sidewalks, crosswalks, and bike lanes.

Based on this analysis, we can identify areas that are not only walkable but also rich in amenities, making them ideal for office spaces. These locations would align with the principle of "getting people to walk ten feet" rather than drive long distances.

---

### **Practical Details**

- **Walkability**: Downtown Austin has a high walkability score due to its compact layout and mix of residential, commercial, and recreational areas.
- **Amenities**:
  - **Restaurants & Cafes**: Numerous options in the downtown area, including popular spots like The Rodeo, Cava, and The Blue Note.
  - **Grocery Stores**: Nearby grocery stores such as Whole Foods, H-E-B, and Publix are within walking distance of many office locations.
  - **Public Transit**: Austin has a robust public transportation system, including the light rail (Aurora Line) and bus services that connect downtown to other parts of the city.
  - **Parks & Recreational Areas**: The Zilker Park and Lady Bird Lake are within walking distance of many office locations in downtown Austin.

---

### **Recommendations**

1. **Office Location A: 200 Congress Avenue, Downtown Austin**  
   - **Walkability Score**: High (9/10)  
   - **Proximity to Amenities**: Within a 5-minute walk to restaurants, cafes, and public transit.  
   - **Accessibility**: Well-connected with sidewalks and bike lanes.  
   - **Reasoning**: This location is ideal for an office due to its high walkability and proximity to essential amenities.

2. **Office Location B: 1001 Red River Street, Downtown Austin**  
   - **Walkability Score**: Medium (7/10)  
   - **Proximity to Amenities**: Within a 10-minute walk to restaurants, cafes, and public transit.  
   - **Accessibility**: Good access with sidewalks but less bike-friendly than Location A.  
   - **Reasoning**: This location is suitable for an office that prioritizes accessibility over extreme walkability.

3. **Office Location C: 500 Congress Avenue, Downtown Austin**  
   - **Walkability Score**: High (9/10)  
   - **Proximity to Amenities**: Within a 5-minute walk to restaurants, cafes, and public transit.  
   - **Accessibility**: Excellent access with sidewalks and bike lanes.  
   - **Reasoning**: This location is ideal for an office that values both walkability and accessibility.

---

### **Sources**

- **Camino AI**: Used to analyze spatial relationships, walkability scores, and proximity to amenities.
- **Web Search**: Used to verify the availability of restaurants, cafes, grocery stores, and public transit options in downtown Austin.

---

**Todos:**
- [Completed] Analyzed walkability and amenities using Camino AI.
- [Completed] Verified practical details with web search.
- [Completed] Synthesized insights into recommendations.

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

🔍 Query 3: Find the best coffee shops for remote work in Paris with good transportation access
============================================================
📋 Response:
- **Task**: Use Gaia Node to find coffee shops in Paris with good transportation access.
- **Task**: Use Camino AI to analyze the spatial relationships and accessibility of these coffee shops.
- **Task**: Use Web Search to verify current reviews, pricing, and opening hours for the top coffee shops.

**Todos:**
1. Use Gaia Node to find coffee shops in Paris with good transportation access.
2. Use Camino AI to analyze the spatial relationships and accessibility of these coffee shops.
3. Use Web Search to verify current reviews, pricing, and opening hours for the top coffee shops.

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

🚀 Advanced Multi-AI Analyses
============================================================

🏢 Comparative Office Location Analysis:
========================================
**Executive Summary:**
A comparative analysis between SoMa (South of Market) and the Mission District in San Francisco reveals distinct characteristics that make each area suitable for different types of tech startups. SoMa is a hub for innovation, with high accessibility, proximity to transit, and a concentration of tech firms and venture capital. The Mission District offers a more diverse cultural atmosphere, affordable housing, and a strong community feel, though it has lower density and less direct access to major transit lines.

**Location Intelligence:**
- **SoMa (South of Market):**
  - **Spatial Relationships:** SoMa is located in the heart of San Francisco’s financial district, adjacent to the Financial District and near the Embarcadero. It is bordered by the Mission Street, Jackson Street, and the Bay. The area is highly connected to other parts of the city via public transit, including the Muni system and BART.
  - **Accessibility:** SoMa has excellent accessibility with multiple bus routes, subway lines (e.g., the Market Street Line), and bike lanes. It is easily reachable from San Francisco International Airport (SFO) via public transportation or car.
  - **Amenities:** The area is rich in amenities such as restaurants, cafes, co-working spaces, and tech firms. It also has a high concentration of venture capital firms and angel investors.
  - **Overall Suitability:** SoMa is highly suitable for tech startups that require proximity to financial institutions, venture capital, and a fast-paced, innovative environment.

- **Mission District:**
  - **Spatial Relationships:** The Mission District is located in the southeastern part of San Francisco, adjacent to the Tenderloin and the East Bay. It is bordered by 16th Street, Mission Street, and the Bay. The area is more spread out compared to SoMa.
  - **Accessibility:** The Mission District has limited direct access to major transit lines like BART or the Muni system. However, it has a strong network of bus routes that connect it to other parts of the city.
  - **Amenities:** The Mission District offers a diverse cultural atmosphere with a wide range of restaurants, shops, and community events. It is also home to several co-working spaces and tech startups, though not as densely concentrated as SoMa.
  - **Overall Suitability:** The Mission District is suitable for tech startups that value a more laid-back, community-oriented environment and are willing to accept slightly longer commutes or less direct access to transit.

**Practical Details:**
- **SoMa:**
  - **Hours of Operation:** Most businesses in SoMa operate from 9 AM to 6 PM, with many co-working spaces open late into the evening.
  - **Pricing:** Office space in SoMa is more expensive compared to other parts of San Francisco due to its proximity to financial institutions and tech firms.
  - **Accessibility:** The area has a high density of parking options, though it can be limited during peak hours.

- **Mission District:**
  - **Hours of Operation:** Most businesses in the Mission District operate from 9 AM to 6 PM, with some co-working spaces open late into the evening.
  - **Pricing:** Office space in the Mission District is more affordable compared to SoMa, though it can vary depending on the specific location and size of the space.
  - **Accessibility:** The area has a strong network of bus routes but limited direct access to major transit lines like BART or the Muni system.

**Recommendations:**
- For tech startups that require proximity to financial institutions, venture capital, and a fast-paced, innovative environment, SoMa is the better choice.
- For tech startups that value a more laid-back, community-oriented environment and are willing to accept slightly longer commutes or less direct access to transit, the Mission District is a good alternative.

**Sources:**
- **Spatial Relationships and Accessibility:** Camino AI
- **Amenities and Overall Suitability:** Gaia Node and Web Search
- **Practical Details (Hours, Pricing, Accessibility):** Web Search

✈️ Specialized Travel Planning:
========================================
I'm delighted to help you plan a luxurious weekend in Napa Valley, focusing on wine tours and fine dining. Let's start by creating a detailed itinerary that balances relaxation, exploration, and indulgence.

### Day 1: Arrival and Wine Tour
**Morning:**
- **Arrival at Napa Valley:** We'll begin with a scenic drive to Napa Valley, where we can enjoy the beautiful vineyards and rolling hills.
- **Check-in at a Luxury Hotel:** We'll check into a high-end hotel in Napa, such as The Ritz-Carlton Napa Valley or Castello di Amorosa. These hotels offer exceptional amenities and views of the valley.

**Afternoon:**
- **Wine Tour:** We'll embark on a guided wine tour to some of the most prestigious wineries in Napa. We'll visit a few top-rated vineyards, such as:
  - **Domaine Carneros:** Known for its sparkling wines and stunning château.
  - **Stag's Leap Wine Cellars:** Famous for its 1973 Cabernet Sauvignon, which won the 1976 Judgement of Paris.
  - **Robert Mondavi Winery:** A historic winery with a rich history in Napa Valley.

**Evening:**
- **Dinner at a Fine Dining Restaurant:** We'll enjoy a gourmet dinner at a highly-rated restaurant in Napa, such as:
  - **The French Laundry (Napa):** A Michelin-starred restaurant offering an exquisite menu.
  - **Bouchon Bistro (Napa):** Known for its creative and flavorful dishes.

### Day 2: Exploring Napa Valley
**Morning:**
- **Breakfast at the Hotel:** We'll start our day with a luxurious breakfast at our hotel, featuring local produce and artisanal products.
- **Wine Tour:** We'll take another wine tour to explore more wineries in Napa. We might visit:
  - **Château Montelena:** A historic vineyard known for its Chardonnay.
  - **Cloudy Bay Winery:** A family-owned winery with a focus on sustainable practices.

**Afternoon:**
- **Relaxation and Leisure:** After our wine tour, we'll have some time to relax at the hotel or take a leisurely walk through the vineyards.
- **Optional Activity:** We might consider an optional activity such as a horseback ride through the valley or a visit to a local art gallery.

**Evening:**
- **Dinner at a Fine Dining Restaurant:** We'll enjoy another gourmet dinner at a highly-rated restaurant in Napa, such as:
  - **The Bistro at Castello di Amorosa:** A unique dining experience set in a medieval-style castle.
  - **Casa Monica:** A charming restaurant with a focus on local and seasonal ingredients.

### Additional Considerations
- **Transportation:** We'll use Camino for optimal routing to ensure we have the most efficient and comfortable travel between locations.
- **Accommodations:** We'll stay at luxury hotels that offer exceptional service, amenities, and views of Napa Valley.
- **Local Insights:** We'll incorporate local insights and cultural context to enhance our experience in Napa Valley.

I'm excited about planning this luxurious weekend in Napa Valley. Let's start by creating a detailed itinerary and ensuring all the necessary tasks are completed. 

### Todos:
1. Confirm hotel reservations for The Ritz-Carlton Napa Valley or Castello di Amorosa.
2. Book guided wine tours to Domaine Carneros, Stag's Leap Wine Cellars, and Robert Mondavi Winery.
3. Reserve dinner at The French Laundry (Napa) and Bouchon Bistro (Napa).
4. Confirm transportation using Camino for optimal routing between locations.
5. Research and incorporate local insights and cultural context for the itinerary.

Let me know if you'd like to make any changes or additions to this plan!

This advanced multi-AI architecture demonstrates how to combine local processing with specialized cloud services to create enterprise-grade location intelligence systems. The layered approach provides:

Cost Efficiency: Use local AI for basic queries, specialized services for complex analysis
Performance Optimization: Intelligent routing and caching
Flexibility: Adaptable to different use cases and complexity levels
Scalability: Handles from simple queries to enterprise analysis

This architecture serves as a foundation for building sophisticated location-aware applications across various industries including real estate, logistics, retail, and urban planning.

Building an AI-Powered Web3 Voting DApp with Gaia

Sushmita - aka meowy — Tue, 09 Sep 2025 12:54:10 +0000

The future of digital democracy isn't just about putting votes on a blockchain—it's about making that interaction as natural as having a conversation. Today, I want to share how I built a Web3 voting application that combines the transparency of blockchain with the intuitive power of AI using Gaia, a decentralized AI infrastructure.

The Vision: Democracy Should Be Conversational

Traditional blockchain interfaces can be intimidating. Users need to understand smart contracts, gas fees, and complex UIs just to cast a simple vote. What if instead, you could just say: "Create a vote about our next team lunch location with options: Pizza, Sushi, Mexican food, lasting for 1 day" and the AI would handle all the blockchain complexity?

That's exactly what this voting DApp does—it bridges the gap between complex blockchain operations and natural human conversation.

Why Gaia? Decentralized AI for Web3

Gaia isn't just another AI API—it's a decentralized computing infrastructure that lets you create, deploy, and scale AI agents. Here's why it was perfect for this project:

True Decentralization

Unlike centralized AI services, Gaia runs on distributed nodes, making it ideal for Web3 applications where decentralization matters. You can run your own node or use the network.

Tool-Calling Capabilities

Gaia's Llama-3-Groq-8B-Tool model excels at function calling, which is crucial for blockchain interactions. The AI can understand natural language commands and translate them into specific smart contract calls.

Blockchain-Native Design

Built with Web3 in mind, Gaia understands the unique requirements of blockchain applications—from handling wallet connections to managing transaction states.

Architecture: Where AI Meets Smart Contracts

The application follows a clean separation of concerns:

Frontend Layer

Built with Next.js and featuring a dual interface:

AI Chat Interface: Natural language interaction with the voting system
Manual Interface: Traditional web forms for users who prefer direct control

AI Integration Layer

The heart of the system is the AI route handler that processes natural language and translates it to blockchain actions:

// AI agent configuration
const openai = createOpenAI({
  baseURL: GAIA_API_ENDPOINT,
  apiKey: "" // Can be empty for local nodes
});

export async function POST(request: Request) {
  const { messages } = await request.json();

  const result = streamText({
    model: openai(GAIA_MODEL),
    system: systemPrompt,
    messages,
    maxSteps: 5,
    tools, // Blockchain interaction tools
  });

  return result.toDataStreamResponse();
}

Blockchain Layer

Smart contracts deployed on Linea Sepolia using a factory pattern:

VotingFactory: Creates new voting instances
VotingBase: Individual voting contracts with options and time limits

Natural Language Commands That Work

The AI agent understands various natural language patterns:

Creating Votes

"Create voting 'What should our next project be?' options: Web App, Mobile App, AI Tool duration: 2"

Viewing Results

"Show all active votings"
"List votings"
"What's the current status of all votes?"

Casting Votes

"Vote for 0x1234...5678 option 2"
"I want to vote for the second option in the contract 0x..."

The AI handles the complexity of:

Parsing natural language intent
Validating contract addresses
Managing transaction states
Providing user feedback

Technical Deep Dive: AI Tools for Blockchain

The magic happens in the AI tools configuration. Here's how the system translates natural language into blockchain actions:

// Example tool for creating votes
{
  name: "createVoting",
  description: "Create a new voting with options and duration",
  parameters: {
    description: "string",
    options: "array of strings", 
    durationType: "number (1=1hour, 2=1day, 3=1week)"
  }
}

When a user says "create a vote about lunch," the AI:

Parses the intent using the Llama-3-Groq-8B-Tool model
Extracts parameters (description, options, duration)
Calls the appropriate tool function
Executes the blockchain transaction via wagmi/viem
Provides natural language feedback to the user

Setting Up Your Own Gaia Node

One of the coolest aspects of this project is that you can run your own AI infrastructure. Here's how:

# Install GaiaNet node
curl -sSfL 'https://github.com/GaiaNet-AI/gaianet-node/releases/latest/download/install.sh' | bash

# Initialize with Llama-3-Groq-8B model (perfect for tool calling)
gaianet init --config https://raw.githubusercontent.com/GaiaNet-AI/node-configs/main/llama-3-groq-8b-tool/config.json

# Start your node
gaianet start

Now your voting DApp runs on completely decentralized infrastructure—no centralized AI service required!

Real-World Impact: Making Web3 Accessible

This project addresses a fundamental challenge in Web3 adoption: complexity barriers. By providing a conversational interface, we enable:

Non-Technical Users

People who find blockchain intimidating can participate naturally through conversation.

Rapid Prototyping

Teams can quickly create polls and votes without navigating complex interfaces.

Educational Value

Users learn about blockchain concepts through guided, conversational interactions.

Challenges Solved and Lessons Learned

State Management Complexity

Managing the relationship between AI conversation state, blockchain transaction state, and UI state required careful architecture. The solution was to keep each layer focused on its core responsibility.

Natural Language Ambiguity

Users don't always express intents clearly. The AI system includes validation and clarification flows to ensure accuracy.

Transaction Feedback

Blockchain transactions take time. The AI provides updates and manages user expectations throughout the process.

Performance and Scalability

The system performs remarkably well:

AI Response Time: ~2-3 seconds for complex operations
Blockchain Integration: Seamless transaction handling with proper error management
User Experience: Natural conversation flow with real-time updates

Future Enhancements

The foundation is strong, and there are exciting possibilities ahead:

Knowledge Base Integration

Gaia supports knowledge bases that could include:

Voting best practices and patterns
Blockchain education materials
Historical voting data and insights
Governance framework documentation

Multi-Chain Support

Expanding beyond Linea to support multiple blockchain networks through the same conversational interface.

Advanced AI Capabilities

Implementing more sophisticated features like:

Vote outcome prediction
Participation analytics
Automated governance suggestions

Open Source and Community

The entire project is open source and available for the community to build upon. Whether you're interested in:

AI and natural language processing
Blockchain development and smart contracts
UX design for Web3 applications
Decentralized infrastructure

There's something here for everyone to learn from and contribute to.

Try It Yourself

Ready to experience conversational blockchain voting? Here's how to get started:

Clone the repository and follow the setup instructions
Deploy your own contracts or use the existing testnet deployment
Configure your Gaia node or use the hosted API
Start voting through natural conversation!

Conclusion: The Future is Conversational

This project represents more than just a voting application—it's a glimpse into a future where interacting with blockchain technology is as natural as having a conversation. By combining Gaia's decentralized AI infrastructure with thoughtful smart contract design, we're not just building applications; we're building the foundation for a more accessible, democratic Web3.

The intersection of AI and blockchain isn't coming—it's here. And with tools like Gaia making decentralized AI infrastructure accessible to developers, the possibilities are limitless.

Want to dive deeper? Check out the full source code and start building your own AI-powered Web3 applications.

Links and Resources:

MCP-Powered Agents: Wiring Gaia to ACI Tools

Tobiloba Adedeji — Fri, 05 Sep 2025 10:17:06 +0000

Most AI demos stop at text. In production, your agent should do things—like starring a repo, creating issues, or labeling PRs—safely, with audit trails and least-privilege access.

This guide shows an end-to-end setup where a Gaia-hosted LLM proposes a tool call and ACI.dev executes it against GitHub on the user’s behalf.

// Detect dark theme var iframe = document.getElementById('tweet-1957763448516862463-563'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1957763448516862463&theme=dark" }

What you’ll build

An agent request like: “Star tobySolutions/stream2peer.”
The model returns a structured tool call (function name + JSON args).
Your server executes it via ACI SDK using the user’s linked GitHub account.
You get a clean, auditable result.

Architecture

Prerequisites

Python 3.10+
Gaia API key and domain (OpenAI-compatible)
Gaia toolkit: https://www.npmjs.com/package/gaia-toolkit
ACI.dev account with:
- A project and default agent
- GITHUB app configured
- Linked GitHub account (via OAuth)
- Agent allowed apps includes GITHUB
- Agent API key (for ACI SDK)

Make sure to use the Gaia toolkit to start and run your Gaia nodes locally.

One-time ACI platform setup

Create/enter project & agent → platform.aci.dev
Configure GITHUB app → App Store → GITHUB → Configure App
Link GitHub account → App Configurations → GITHUB → Add Account → Start OAuth2 Flow Choose a **linked account owner id* (e.g., tobySolutions). You’ll use this in code.
Allow agent to use GITHUB → Project Settings → Manage Project → Agent → Edit → ALLOWED APPS: GITHUB
Copy the agent API key

Environment

Create .env in your project root:

# Gaia
GAIA_BASE_URL=https://YOUR-GAIA-DOMAIN/v1
GAIA_API_KEY=your_gaia_api_key

# ACI
ACI_API_KEY=your_aci_agent_api_key
ACI_OWNER_ID=   # your linked account owner id chosen during OAuth link

Install dependencies

# pip
pip install --upgrade pip
pip install openai python-dotenv aci

# or with uv
uv pip install openai python-dotenv aci

Some environments publish the package as aci (not aci-sdk). Use Python 3.10+.

Minimal working example

Goal: Tell the model the GITHUB “star repo” function exists, let it propose a tool call, then execute it via ACI.

# main.py
import os, json
from dotenv import load_dotenv
from openai import OpenAI
from aci import ACI

load_dotenv()

# --- Clients ---
llm = OpenAI(
    base_url=os.getenv("GAIA_BASE_URL"),      # Gaia’s OpenAI-compatible endpoint
    api_key=os.getenv("GAIA_API_KEY"),
)
aci = ACI()                                   # uses ACI_API_KEY from .env

OWNER_ID = os.getenv("ACI_OWNER_ID")          # linked account owner id

def main() -> None:
    # 1) Discover the function schema from ACI
    github_star_repo_fn = aci.functions.get_definition("GITHUB__STAR_REPOSITORY")

    # 2) Ask the model to do the task, including the tool schema
    resp = llm.chat.completions.create(
        model="Llama-3-Groq-8B-Tool",         # pick a tool-capable model available on your Gaia node
        messages=[
            {"role": "system", "content": "You are a helpful assistant with access to tools."},
            {"role": "user", "content": "Star the tobySolutions/stream2peer GitHub repository for me."},
        ],
        tools=[github_star_repo_fn],
        tool_choice="required",               # force a demo tool call; drop in prod
    )

    msg = resp.choices[0].message
    tool_call = msg.tool_calls[0] if msg.tool_calls else None
    if not tool_call:
        print("Model replied with text only:", msg.content)
        return

    # 3) Execute the function via ACI (server-side, with your credentials)
    args = json.loads(tool_call.function.arguments or "{}")
    # Optional guardrail: only allow your org
    if args.get("owner") != "tobySolutions":
        raise ValueError("Blocked: only allowed to act for owner=tobySolutions")

    result = aci.handle_function_call(
        tool_call.function.name,              # "GITHUB__STAR_REPOSITORY"
        args,                                 # {"owner": "...", "repo": "..."}
        linked_account_owner_id=OWNER_ID,
    )
    print("ACI result:", result)

if __name__ == "__main__":
    main()

Run it:

python main.py

Expected flow:

LLM returns a tool call like:

   `{"name":"GITHUB__STAR_REPOSITORY","arguments":     {"owner":"tobySolutions","repo":"stream2peer"}}`

Your server calls aci.handle_function_call(...) with your linked account owner id.
GitHub stars the repository; you see a success payload.

Why this pattern works

Discover: Fetch the exact function schema from ACI; pass it to the model.
Constrain: The model can only call what you expose.
Execute: Your backend holds credentials; the model never sees tokens.
Audit: You can log every call and enforce org/repo allowlists.

Extending beyond “star repo”

Discover more ACI functions and expose them to the model:

issue_create = aci.functions.get_definition("GITHUB__CREATE_ISSUE")
comment_pr  = aci.functions.get_definition("GITHUB__COMMENT_ON_PR")

tools = [github_star_repo_fn, issue_create, comment_pr]
resp = llm.chat.completions.create(
  model="Llama-3-Groq-8B-Tool",
  messages=[...],
  tools=tools,
  tool_choice="auto",
)

Your server logic remains the same—just route the selected tool call to aci.handle_function_call(...).

Troubleshooting

No tool call generated
Ensure the function schema is in tools=[...]. For demos, keep tool_choice="required".
Permission errors
Confirm: GITHUB app configured, GitHub account linked, agent allowed to use GITHUB.
Wrong owner
The linked_account_owner_id must match the id you chose during account linking (e.g., tobySolutions).
Package install issues
Use aci (not aci-sdk) and Python 3.10+. Upgrade pip if needed.

MCP note

If you’re building an MCP stack, expose ACI tools via an MCP server so any MCP-aware client (including ones running against Gaia) can discover and call them. The execution layer—ACI—stays the same.

Wrap-up

You now have a clean pattern to turn LLM intent into real actions using Gaia for inference and ACI.dev for tool execution.
Swap the function, keep the shape, and your agent can open issues, label PRs, or post to Slack—safely and audibly.

Getting Started with Gaia: A Developer's Guide to Building AI Agents with Gaia

Sushmita - aka meowy — Thu, 04 Sep 2025 13:05:00 +0000

Building AI-powered applications can be daunting. Between choosing the right models, setting up infrastructure, and handling API integrations, developers often spend more time on setup than on building their actual product. That's where the Gaia Agent Starter Kit comes in—a streamlined foundation that gets you from idea to working AI application in minutes, not hours.

Why Another AI Starter Kit?

The AI development landscape is cluttered with complex frameworks and heavyweight solutions. Most require extensive configuration, vendor lock-in, or compromise on performance and privacy. Gaia's approach is different:

Decentralized by design - No single point of failure or vendor dependency
Privacy-focused - Your data stays where you want it
Developer-friendly - Clean APIs and straightforward integration
Production-ready - Built on proven infrastructure

This starter kit distills years of AI application development experience into a simple, extensible foundation.

The Starter Kit Architecture

The Gaia Agent Starter Kit follows a clean, modular architecture built on Next.js:

Core Components

Frontend Layer: A clean React interface with streaming chat capabilities
API Integration: Streamlined connection to Gaia's AI infrastructure

Tool System: Extensible framework for adding custom AI capabilities
Configuration Management: Simple environment-based setup

Quick Start: From Clone to Chat in 5 Minutes

Step 1: Project Setup

git clone https://github.com/meowyx/gaia-agent-starter
cd gaia-agent-starter
pnpm install

The project uses pnpm for faster dependency installation, but works with npm or yarn as well.

Step 2: Get Your Gaia API Credentials

The setup process is straightforward:

Visit gaianet.ai and click Launch App
Connect your wallet - MetaMask or other Web3 wallets work
Access settings via the profile dropdown
Create an API key in the "Gaia API Keys" section
Choose your base URL from available public nodes

Step 3: Environment Configuration

Create your .env.local file:

NEXT_PUBLIC_GAIA_API_BASE_URL=
NEXT_PUBLIC_GAIA_API_KEY=your_api_key_here

Step 4: Launch Your AI Agent

pnpm dev

Open http://localhost:3000 and start chatting with your AI agent.

Under the Hood: How It Works

API Route Implementation

The core API route demonstrates clean integration with Gaia:

import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";
import { tools } from "@/ai/tools";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const openai = createOpenAI({
    baseURL: process.env.NEXT_PUBLIC_GAIA_API_BASE_URL,
    apiKey: process.env.NEXT_PUBLIC_GAIA_API_KEY 
  });

  try {
    const result = streamText({
      model: openai("llama"),
      system: "you are a friendly assistant",
      messages,
      maxSteps: 5,
      tools,
    });

    return result.toDataStreamResponse();
  } catch (error) {
    console.error(error);
    return new Response("Internal server error", { status: 500 });
  }
}

This approach provides:

Environment-based configuration - No hardcoded values
Error handling - Graceful failure management
Streaming responses - Real-time conversation flow
Tool integration - Extensible AI capabilities

Frontend Integration

The frontend uses a clean, welcoming interface:

export default function Home() {
  return (
    <div 
      className="h-screen w-full overflow-y-auto grid grid-rows-[20px_1fr_60px]"
      style={{ 
        background: "linear-gradient(135deg, #fcf8e8 0%, #d4e2d4 100%)",
      }}
    >
      <main className="gap-8 row-start-2 sm:items-start h-full w-full">
        <div className="flex flex-col gap-3 items-center justify-center h-full">
          <div className="text-center mb-6">
            <h1 className="text-3xl font-bold mb-2 text-green-800">
              Hi there, Let's Chat 👋
            </h1>
            <p className="text-sm text-green-600 italic">
              powered by <Link href="https://www.gaianet.ai/">gaia</Link> 🌱
            </p>
          </div>
          <Chat />
        </div>
      </main>
    </div>
  );
}

The design emphasizes:

Approachable aesthetics - Warm, natural color scheme
Clear branding - Gaia attribution and links
Responsive layout - Works across all device sizes
Accessibility - Proper semantic structure

Customization and Extension

Adding Custom Tools

The starter kit includes a tools system for extending AI capabilities:

// ai/tools.ts
export const tools = {
  getCurrentTime: {
    description: 'Get the current time',
    parameters: z.object({}),
    execute: async () => {
      return new Date().toISOString();
    },
  },

  // Add your custom tools here
  calculateTip: {
    description: 'Calculate tip amount',
    parameters: z.object({
      amount: z.number(),
      percentage: z.number()
    }),
    execute: async ({ amount, percentage }) => {
      return amount * (percentage / 100);
    },
  }
};

Customizing the AI Personality

Modify the system prompt to change your agent's behavior:

const result = streamText({
  model: openai("llama"),
  system: `You are a specialized assistant for [your domain].
           You should:
           - Be helpful and accurate
           - Focus on [your specific area]
           - Provide actionable advice
           - Ask clarifying questions when needed`,
  messages,
  maxSteps: 5,
  tools,
});

Styling and Branding

The starter kit uses Tailwind CSS for easy customization:

/* Custom color scheme */
:root {
  --primary-green: #16a34a;
  --accent-green: #22c55e;
  --background-start: #fcf8e8;
  --background-end: #d4e2d4;
}

Production Deployment

Environment Configuration

For production deployment, ensure your environment variables are properly set:

# Production environment
NEXT_PUBLIC_GAIA_API_BASE_URL=
NEXT_PUBLIC_GAIA_API_KEY=your_production_api_key

Performance Optimizations

The starter kit includes several built-in optimizations:

Automatic code splitting - Next.js handles this automatically
Image optimization - Built-in Next.js image optimization
Streaming responses - Reduces perceived latency
Error boundaries - Graceful error handling

Security Considerations

While the starter kit is secure by default, consider these additional measures for production:

// Add rate limiting
import { rateLimit } from '@/lib/rate-limit';

export async function POST(request: Request) {
  const identifier = request.headers.get('x-forwarded-for') || 'localhost';
  const { success } = await rateLimit.limit(identifier);

  if (!success) {
    return new Response('Too many requests', { status: 429 });
  }

  // ... rest of your handler
}

Common Use Cases and Extensions

Customer Support Agent

Transform the starter into a support agent:

const supportSystem = `You are a customer support agent for [Company Name].
You have access to:
- Product documentation
- Order lookup tools  
- Troubleshooting guides

Always be helpful, patient, and professional.`;

Educational Tutor

Create a specialized learning assistant:

const tutorSystem = `You are an educational tutor specializing in [Subject].
You should:
- Break down complex concepts
- Provide examples and practice problems
- Adapt to the student's level
- Encourage learning`;

Developer Assistant

Build a coding companion:

const devSystem = `You are a senior developer assistant.
You can help with:
- Code review and suggestions
- Debugging assistance
- Architecture recommendations
- Best practices guidance`;

Connecting to Your Own Gaia Node

For maximum control and privacy, you can run your own Gaia node:

Local Node Setup

# Install Gaia node
curl -sSfL 'https://github.com/GaiaNet-AI/gaianet-node/releases/latest/download/install.sh' | bash

# Initialize with your preferred model
gaianet init --config https://raw.githubusercontent.com/GaiaNet-AI/node-configs/main/llama-3-groq-8b-tool/config.json

# Start your node
gaianet start

Configuration Update

Update your environment variables to point to your local node:

NEXT_PUBLIC_GAIA_API_BASE_URL=http://localhost:8080/v1
NEXT_PUBLIC_GAIA_API_KEY=""  # Can be empty for local nodes

Troubleshooting Common Issues

API Connection Problems

If you're having trouble connecting to Gaia:

Verify your API key - Ensure it's correctly set in .env.local
Check the base URL - Confirm the node is accessible
Review network settings - Firewall or proxy issues
Check rate limits - Some nodes have usage restrictions

Streaming Response Issues

If messages aren't streaming properly:

Browser compatibility - Ensure modern browser support
Network configuration - Some proxies block streaming
Error handling - Check browser console for errors

Tool Integration Problems

If custom tools aren't working:

Parameter validation - Ensure Zod schemas are correct
Async handling - All tool functions should be async
Error boundaries - Add proper error handling

Advanced Patterns

Multi-Agent Conversations

Extend the starter to support multiple AI agents:

const agents = {
  researcher: {
    system: "You are a research specialist...",
    model: "llama"
  },
  writer: {
    system: "You are a creative writer...",
    model: "llama"
  }
};

// Route to different agents based on context
const selectedAgent = agents[agentType];

Context Persistence

Add conversation memory:

// Store conversation context
const conversation = {
  id: generateId(),
  messages: [],
  context: {},
  created: new Date()
};

// Retrieve and maintain context across sessions

Integration with External APIs

Add external data sources:

const tools = {
  getWeather: {
    description: 'Get current weather',
    parameters: z.object({
      location: z.string()
    }),
    execute: async ({ location }) => {
      const response = await fetch(`https://api.weather.com/${location}`);
      return await response.json();
    }
  }
};

Community and Ecosystem

The Gaia Agent Starter Kit is part of a growing ecosystem:

Community Resources

GitHub Discussions - Share experiences and get help
Discord Community - Real-time chat with other developers
Documentation - Comprehensive guides and tutorials
Example Projects - Inspiration and code samples

Contributing Back

Ways to contribute to the ecosystem:

Share your extensions - Tools, UI components, integrations
Submit bug reports - Help improve stability
Write tutorials - Help others learn
Contribute code - Direct improvements to the starter kit

The Future of AI Development

This starter kit represents a philosophy shift in AI development:

From Complexity to Simplicity

Instead of overwhelming developers with options, provide a clean foundation they can build upon.

From Centralized to Decentralized

Remove single points of failure and give developers control over their AI infrastructure.

From Proprietary to Open

Open-source tools and transparent infrastructure enable innovation and trust.

Conclusion: Getting started with your AI Agent Journey

The Gaia Agent Starter Kit removes the friction from AI application development. Whether you're building a customer service bot, an educational tutor, or a specialized domain assistant, this foundation gives you everything you need to start building immediately.

The real power comes from what you build on top of it. The starter kit is intentionally minimal—a clean canvas for your ideas rather than a prescriptive framework. This approach enables rapid prototyping while maintaining the flexibility to scale and customize as your application grows.

Ready to build your first AI agent? Clone the repository, follow the setup guide, and start experimenting.

Getting Started:

Building an AI-Powered Minecraft Agent with Gaia

Tobiloba Adedeji — Tue, 02 Sep 2025 09:22:39 +0000

Minecraft has always been a sandbox for creativity. But what if you could have an AI teammate inside your world—able to chat, mine, build, and follow your instructions in natural language?

That’s exactly what I built using Gaia’s decentralized AI, LangChain, and mineflayer.

// Detect dark theme var iframe = document.getElementById('tweet-1929930385535726024-105'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1929930385535726024&theme=dark" }

The In-Game Assistant Challenge

Minecraft bots aren’t new, but they’re often:

Scripted → Hardcoded to do specific tasks, not flexible.
Centralized → Dependent on APIs like OpenAI, costly and limiting.
Rigid → Only respond to strict commands, no conversational flow.

I wanted something better:

A bot that understands natural language.
Powered by decentralized AI (Gaia).
Flexible enough to mine, build, follow, and adapt to tasks.

Solution: Gaia + LangChain + Mineflayer

The solution combines three technologies:

mineflayer → the library that lets you control Minecraft bots programmatically.
LangChain → an agent framework that allows tool-calling.
Gaia → decentralized LLMs running on open infrastructure.
Gaia toolkit → https://www.npmjs.com/package/gaia-toolkit

Together, they enable a smart Minecraft companion.

Architecture: From Chat to Action

Here’s the high-level design:

Player messages → sent in chat.
Bot → listens and processes input.
LangChain agent → decides which action/tool to execute.
Gaia node → provides LLM reasoning.
Mineflayer → carries out the command in Minecraft.

Bot Setup

First, spin up the Minecraft bot and connect to your server:

import { createBot } from "mineflayer";
import { pathfinder } from "mineflayer-pathfinder";

const bot = createBot({
  host: "localhost",
  port: 25565,
  username: "Gaiabot",
});

bot.loadPlugin(pathfinder);

bot.once("spawn", () => {
  console.log("Gaiabot ready.");
  bot.chat("Hello! I'm online and ready to help with Minecraft tasks!");
});

✅ This ensures the bot logs into your server and greets you when it’s ready.

LLM Integration with Gaia

Next, connect the bot to a Gaia domain node. This provides decentralized inference using Meta Llama-3.1.

import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "Meta-Llama-3.1-8B-Instruct-Q5_K_M",
  configuration: {
    apiKey: process.env.GAIA_API_KEY,
    baseURL: "https://node_id.gaia.domains/v1",
  },
  temperature: 0.3,
});

With this setup, you’re running on Gaia’s decentralized network, not a centralized API.

It is recommended that you also run a node locally and use it with your agent directly - Gaia toolkit works perfectly here.

Dynamic Tools: Giving the Bot Superpowers

The core innovation is the tool system. Tools are structured actions the AI can call. For example, here’s the mining tool:

new DynamicTool({
  name: "mine_block",
  description: "Mine a specific type of block near the bot",
  func: async (blockType: string) => {
    const block = bot.findBlock({
      matching: (blk: any) => blk.name.includes(blockType.toLowerCase()),
      maxDistance: 32,
    });

    if (!block) return `No ${blockType} found nearby.`;

    await (bot as any).collectBlock.collect(block);
    return `Mined ${block.name} at ${block.position}`;
  },
});

Other tools include:

place_block → place blocks from inventory.
follow_player → follow a player around.
go_to_player → walk to a player’s position.
check_inventory → list what’s in the bot’s inventory.
stop_movement → halt all actions.

✅ Tools map natural language → structured actions → in-game results.

Handling Player Chat Commands

Some commands bypass the AI for instant execution:

bot.on("chat", async (username, message) => {
  if (message === "!inventory") {
    const items = bot.inventory
      .items()
      .map((i: any) => `${i.name} x${i.count}`)
      .join(", ");
    return bot.chat(items || "I have nothing right now.");
  }

  if (message === "!stop") {
    bot.pathfinder.setGoal(null);
    return bot.chat("Stopped all movement.");
  }
});

✅ This makes the bot responsive for common tasks while still allowing AI reasoning for more complex ones.

AI in Action

When a player sends a free-form request, the bot routes it through Gaia + LangChain:

const response = await chain.invoke({
  input: `Player ${username} says: ${message}`,
});

bot.chat(response.output.slice(0, 100)); // keep short for chat

Example interaction:

Player: Can you mine some coal?
Bot: Looking for coal to mine...
Bot: Successfully mined coal at (23, 65, -110).

✅ The bot thinks, acts, and reports back naturally.

User Experience Design

Several small design details improve the experience:

Thinking feedback → Bot says “Let me help you with that…” before acting.
Error handling → Fallback responses if a tool fails.
Short replies → Truncated answers to fit Minecraft chat.
Graceful shutdown → Safe disconnect on SIGINT.

These touches make the bot feel less like a script and more like a companion.

Real-World Use Cases

Survival helper → Automate mining, building, and farming.
Learning companion → Teach new players basic tasks.
Server assistant → Handle repetitive chores.
AI experiments → Extend tools for crafting, farming, or multiplayer collaboration.

Deployment & Configuration

Clone the repo:

   git clone https://github.com/GaiaNet-AI/gaia-cookbook
   cd javascript-typescript/minecraft-gaia-agent

Install dependencies:

   npm install

Add your Gaia API key in .env:

   GAIA_API_KEY=your_key_here

Start a Minecraft server (local or hosted).
Run the bot:

   npm start

Jump in-game and start chatting with your AI teammate 🎮

Why Gaia’s Decentralized Approach Matters

Traditional AI bots rely on closed APIs. Gaia’s decentralized LLMs give:

Freedom → no reliance on OpenAI or other providers.
Customization → swap in different Gaia domains and models.
Community scaling → open-source, extensible, and composable.

For Minecraft, this means developers can create smarter bots without lock-in.

Future Enhancements

Crafting recipes → AI learns how to craft items.
Multi-agent collaboration → multiple bots cooperating.
On-chain connections → link Minecraft events to blockchain actions.
Educational use → AI tutors inside Minecraft servers.

Conclusion: More Than a Minecraft Mod

The Minecraft Gaia Agent is more than just a fun experiment. It’s a blueprint for AI companions in games, simulations, and beyond.

By combining Gaia’s decentralized AI, LangChain’s tool-calling, and mineflayer’s Minecraft API, we created a bot that can understand, act, and evolve.

👉 Explore the repo: Minecraft Gaia Agent
👉 Learn more about Gaia: GaiaNet.ai

Building a Deep Research Agent with Gaia: Multi-Agent Planning and Execution

Sushmita - aka meowy — Mon, 01 Sep 2025 16:08:12 +0000

Research is no longer just about finding information—it's about intelligent synthesis, strategic planning, and adaptive depth exploration.

Today, I want to share how I built a sophisticated AI research agent using Gaia's decentralized infrastructure that doesn't just search the web, but thinks like a professional researcher.

// Detect dark theme var iframe = document.getElementById('tweet-1920080467069726994-131'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1920080467069726994&theme=dark" }

The Challenge: Beyond Simple Search

Traditional search tools give you results. Research agents give you insights. The difference lies in their ability to:

Plan strategically rather than search randomly
Evaluate quality rather than just rank by relevance
Synthesize findings rather than present raw data
Adapt their approach based on what they discover

Sounds complicated? Think of it in this way:

In this case the architecture would be something like this:

This research agent embodies all these capabilities through a multi-agent architecture that mirrors how human researchers actually work.

Architecture: A Symphony of Specialized Agents

The system consists of three core agents working in harmony, let's explore how everything works together.

Planning Agent: The Strategic Mind

Built with Gaia's Llama-3-Groq-8B-Tool model, this agent creates comprehensive research plans:

// Research planning with structured steps
const plan = await planner.createPlan(query);

// Each plan contains:
{
  query: "Original research question",
  steps: [
    {
      id: 1,
      description: "Search for recent developments",
      action: { type: 'search', params: { query: '...' }},
      status: 'pending'
    }
  ]
}

Execution Agent: The Workhorse

Handles the actual research tasks with multiple specialized tools:

switch (currentStep.action.type) {
  case 'search':
    result = await searchTool.search(query);
    break;
  case 'summarize':
    result = await summarizationTool.synthesize(findings);
    break;
  case 'fetch_webpage':
    result = await webTool.extractContent(url);
    break;
  // Additional tools for papers, GitHub repos, etc.
}

The Deep Thinker

The most sophisticated component—it decides when and how to dig deeper:

// Dynamic plan expansion based on findings
const additionalSteps = await generateText({
  model: openai('gpt-4'),
  messages: [
    {
      role: "system", 
      content: "Analyze research gaps and create deeper investigation steps..."
    }
  ]
});

Stateful Research Workflows

Unlike stateless APIs, this research agent maintains context throughout the entire research journey:

interface ResearchSession {
  id: string;
  plan: ResearchPlan;
  currentStepIndex: number;
  artifacts: ResearchArtifact[];
  createdAt: string;
}

// Persistent session storage
const sessions: Record<string, ResearchSession> = {};

This allows the agent to:

Remember previous findings when planning next steps
Build upon earlier research in subsequent queries
Track progress through complex multi-step investigations
Resume research if interrupted

The "Dig Deeper" Innovation

The breakthrough feature is the agent's ability to intelligently expand its own research plan. When you click "Dig Deeper," here's what happens:

1. Gap Analysis

The agent analyzes completed research to identify knowledge gaps:

// The agent examines all artifacts collected so far
const { plan, artifacts } = session;

// And asks: "What haven't we explored yet?"
const analysisPrompt = `
Based on the research conducted so far, identify areas that need deeper investigation.
Current findings: ${JSON.stringify(artifacts)}
What 2-3 additional research steps would provide deeper insights?
`;

2. Strategic Expansion

Rather than random additional searches, it creates targeted investigation steps:

[
  {
    "id": 4,
    "description": "Investigate the technical implementation challenges",
    "action": {
      "type": "search",
      "params": {
        "query": "technical challenges implementing quantum computing in healthcare"
      }
    },
    "dependencies": [1, 2]
  }
]

3. Contextual Execution

New steps build upon previous findings using the dependency system:

// Find relevant artifacts from previous steps
if (currentStep.dependencies) {
  for (const depId of currentStep.dependencies) {
    const depArtifact = artifacts.find(a => a.taskId === depId);
    if (depArtifact && depArtifact.taskType === 'search') {
      searchResults = depArtifact.artifact as ProcessedSearchResult[];
    }
  }
}

Real-Time Research Orchestration

The execution engine manages complex workflows with proper error handling and progress tracking:

export async function POST(request: Request) {
  const { sessionId } = await request.json();
  const session = sessions[sessionId];

  // Execute current step
  const currentStep = plan.steps[currentStepIndex];
  currentStep.status = 'in-progress';

  try {
    // Execute based on step type
    const result = await executeStep(currentStep);

    // Store results as artifacts
    artifacts.push({
      taskId: currentStep.id,
      taskType: currentStep.action.type,
      artifact: result
    });

    currentStep.status = 'completed';
    session.currentStepIndex++;

    return { result, isComplete: currentStepIndex >= plan.steps.length };
  } catch (error) {
    currentStep.status = 'failed';
    throw error;
  }
}

Advanced Features: Beyond Basic Research

Quality Assessment

The agent doesn't just collect information—it evaluates source credibility, recency, and relevance:

class WebSearchTool {
  processResults(rawResults: any[]): ProcessedSearchResult[] {
    return rawResults.map(result => ({
      title: result.title,
      url: result.url,
      summary: this.extractSummary(result.content),
      source: this.identifySource(result.url),
      date: this.extractDate(result),
      credibilityScore: this.assessCredibility(result),
      keyPoints: this.extractKeyPoints(result.content)
    }));
  }
}

Intelligent Synthesis

The summarization tool creates coherent narratives from disparate sources:

class SummarizationTool {
  async summarize(query: string, searchResults: ProcessedSearchResult[]): Promise<string> {
    // Combines findings from multiple sources
    // Identifies patterns and contradictions  
    // Creates structured summaries
    // Highlights key insights
  }
}

Adaptive Interface

The frontend provides real-time feedback on which agents are active:

// Visual indicators for active processes
const [activeFeatures, setActiveFeatures] = useState({
  search: false,    // Web search in progress
  planning: false,  // Creating research plan
  quality: false,   // Evaluating source quality
  synthesis: false, // Synthesizing findings
  depth: false      // Digging deeper
});

Why Gaia Makes This Possible

Decentralized Intelligence

Unlike centralized AI services, Gaia's distributed architecture ensures:

No single point of failure for critical research workflows
Data privacy - research stays within your infrastructure
Cost efficiency - run your own nodes instead of paying per API call
Customization - fine-tune models for specific research domains

Tool-Calling Excellence

Gaia's Llama-3-Groq-8B-Tool model excels at structured tool usage:

// The model understands complex tool interactions
const tools = {
  search: { /* Web search capabilities */ },
  summarize: { /* Content synthesis */ },
  fetch_webpage: { /* Content extraction */ },
  dig_deeper: { /* Plan expansion */ }
};

// And orchestrates them intelligently
const result = await streamText({
  model: openai(GAIA_MODEL),
  tools,
  maxSteps: 5, // Multi-step reasoning
});

Real-World Research Scenarios

Academic Research

Query: "Latest developments in quantum computing for healthcare applications"

Plan Generated:
1. Search recent academic papers on quantum healthcare
2. Fetch specific papers from top conferences  
3. Analyze implementation challenges
4. Summarize potential applications
5. [Dig Deeper] Investigate regulatory considerations
6. [Dig Deeper] Explore current pilot programs

Market Analysis

Query: "Competitive landscape for AI-powered customer service tools"

Plan Generated:
1. Search major players in AI customer service
2. Fetch company websites and product pages
3. Analyze pricing models and features
4. Summarize competitive positioning
5. [Dig Deeper] Investigate recent funding rounds
6. [Dig Deeper] Analyze customer reviews and case studies

Technical Investigation

Query: "Performance comparison of Next.js vs React for large-scale applications"

Plan Generated:
1. Search performance benchmarks
2. Fetch GitHub repositories with comparisons
3. Analyze real-world case studies
4. Summarize trade-offs and recommendations  
5. [Dig Deeper] Investigate deployment patterns
6. [Dig Deeper] Explore migration strategies

Performance and Scalability

The agent delivers impressive performance across key metrics:

Research Plan Generation: ~3-5 seconds for complex topics
Step Execution: ~2-4 seconds per research step
Deep Research Expansion: ~5-8 seconds for additional planning
Session Management: Handles multiple concurrent research workflows
Memory Efficiency: Stores only essential artifacts and findings

Error Handling and Resilience

The system includes comprehensive error handling for real-world reliability:

try {
  const result = await executeStep(currentStep);
  currentStep.status = 'completed';
} catch (error) {
  currentStep.status = 'failed';

  // Detailed error reporting
  return NextResponse.json({ 
    error: 'Step execution failed',
    details: error.message,
    stepId: currentStep.id,
    recoveryOptions: ['retry', 'skip', 'modify']
  });
}

Setting Up Your Research Agent

Quick Start with Gaia API

// Simple configuration
const GAIA_API_ENDPOINT = 'API_ENDPOINT';
const GAIA_MODEL = 'Llama-3-Groq-8B-Tool';

// Add your API key
process.env.GAIA_API_KEY = 'your_key_here';

Self-Hosted for Maximum Control

# Install and run your own Gaia node
curl -sSfL 'https://github.com/GaiaNet-AI/gaianet-node/releases/latest/download/install.sh' | bash
gaianet init --config https://raw.githubusercontent.com/GaiaNet-AI/node-configs/main/llama-3-groq-8b-tool/config.json
gaianet start

# Point your application to local node
const GAIA_API_ENDPOINT = 'http://localhost:8080/v1';

Future Enhancements: The Research Agent Evolution

Knowledge Base Integration

Gaia's knowledge base system could enhance the agent with:

Domain-specific expertise - Specialized knowledge for different fields
Historical context - Learning from previous successful research patterns
Quality heuristics - Improved source evaluation based on domain knowledge
Citation networks - Understanding relationships between sources

Multi-Modal Research

Expanding beyond text to include:

Image analysis for visual research
Video content processing for multimedia sources
Audio transcription for podcast and interview analysis
Document parsing for PDFs and technical papers

Collaborative Research

Multiple agents working together:

Specialist agents for different domains
Verification agents for fact-checking
Synthesis agents for cross-domain insights
Presentation agents for formatted output

Open Source Impact

The complete research agent is available as an open-source project, enabling:

Educational use - Understanding multi-agent AI systems
Research applications - Academic and professional research workflows
Commercial adaptation - Building specialized research tools
Community contribution - Collaborative improvements and extensions

Conclusion: The Future of AI-Powered Research

This research agent represents a fundamental shift from reactive search to proactive investigation. By combining Gaia's decentralized AI infrastructure with sophisticated multi-agent orchestration, we've created a system that doesn't just find information—it conducts research.

The implications extend far beyond individual productivity:

Academic researchers can explore complex topics more comprehensively
Business analysts can conduct thorough market investigations
Students can learn research methodologies through AI guidance
Organizations can build institutional knowledge through systematic investigation

As AI agents become more sophisticated, the boundary between human and artificial research capabilities continues to blur. The key insight from this project is that the future lies not in replacing human researchers, but in amplifying their capabilities through intelligent, strategic, and adaptive AI partners.

Resources:

Adding Observability to Your AI App in 5 Minutes

Harish Kotra (he/him) — Fri, 29 Aug 2025 11:34:00 +0000

How I stopped guessing why my AI failed and started actually knowing

The "It Worked on My Machine" Problem

So you've built something cool. You're using an OpenAI compatible API (maybe from Gaia) to power a chatbot, a content generator, or some other AI magic. You've tested it, it works perfectly, and you deploy it with confidence.

Then the first user report comes in: "The AI is giving weird answers."

Sound familiar? You check your logs. You see that an API call was made. You see that it succeeded. But you have no idea what was asked or what was returned. You're left guessing in the dark.

This was me until last week. I was building AI features blindfolded.

The Lightbulb Moment: Observability

I learned that there's a difference between just "working" and being "observable."

Working means your code doesn't crash.

Observable means you can actually understand why it behaves the way it does.

Think of it like this: if your AI app were a car, working would mean the engine turns on. Observable would mean you have a dashboard with a speedometer, fuel gauge, and check engine lights.

The 5-Minute Solution That Changed Everything

I discovered Langfuse, an open-source observability platform, and realized I could add proper monitoring to my AI app by changing literally one line of code.

No exaggeration. Here's what I changed:

# Before (what I was doing)
import openai

# After (the magic line)
from langfuse.openai import openai

That's it. By changing the import, every call to my Gaia node (or any OpenAI-compatible API) became automatically traced, monitored, and visible.

What This Actually Gets You

After making that one change, I suddenly had:

A complete history of every question users asked and every answer the AI gave
Performance metrics showing how long each call took and how many tokens were used
Cost tracking to understand which features were expensive to run
Error monitoring that showed me exactly where things went wrong

Most importantly, when another "weird answer" report came in, I could actually look up the exact conversation and understand what happened.

Let Me Show You How to Set This Up

I've put together a complete example you can run yourself. Here's what you'll need:

A Gaia Node URL (launch your own node) and API key* (if you're using one of Gaia's public domains only)
A Langfuse account (free sign up here)
Python installed on your computer

Step 1: Get Your Credentials

Step 2: The Code

Create a new file called app.py and paste this code:

import streamlit as st
import os
from langfuse.openai import openai

# Simple configuration
st.sidebar.title("🔧 Configuration")
gaia_api_key = st.sidebar.text_input("Gaia API Key", type="password")
gaia_base_url = st.sidebar.text_input("Gaia Base URL", "https://your-gaia-node-url.gaia.domains/v1")
langfuse_public_key = st.sidebar.text_input("Langfuse Public Key", type="password")
langfuse_secret_key = st.sidebar.text_input("Langfuse Secret Key", type="password")

# Set environment variables for Langfuse
if langfuse_public_key and langfuse_secret_key:
    os.environ["LANGFUSE_PUBLIC_KEY"] = langfuse_public_key
    os.environ["LANGFUSE_SECRET_KEY"] = langfuse_secret_key
    os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"

st.title("🚀 Gaia Node + Langfuse Demo")

# Set up the magic connection
def initialize_gaia_client():
    try:
        client = openai.OpenAI(
            base_url=gaia_base_url,
            api_key=gaia_api_key,
            default_headers={
                "HTTP-Referer": "https://gaia-langfuse-demo.streamlit.app",
                "X-Title": "Gaia Node Langfuse Demo",
            }
        )
        return client
    except Exception as e:
        st.error(f"Error initializing client: {e}")
        return None

# Ask a question
user_input = st.text_area(
    "Enter your message:",
    "Explain the concept of black holes in simple terms.",
    height=100
)

if st.button("Send Message"):
    if not all([langfuse_public_key, langfuse_secret_key, gaia_api_key]):
        st.error("Please enter all API keys in the sidebar")
    else:
        client = initialize_gaia_client()
        if client:
            try:
                with st.spinner("Making request to Gaia Node..."):
                    response = client.chat.completions.create(
                        name="gaia-chat-request",
                        model="Qwen3-4B-Q5_K_M",
                        messages=[
                            {"role": "system", "content": "You are a helpful assistant specialized in astronomy."},
                            {"role": "user", "content": user_input}
                        ],
                        max_tokens=300,
                        temperature=0.7,
                        metadata={"demo_type": "simple_chat"}
                    )

 result = response.choices[0].message.content

                    st.success("✅ Request completed!")
                    st.subheader("Response:")
                    st.write(result)

                    st.info("📊 Check your Langfuse dashboard for tracing and analytics!")

            except Exception as e:
                st.error(f"❌ Error: {e}")

Step 3: Run It

Install the requirements:

pip install langfuse openai streamlit

Run the app:

streamlit run app.py

That's it! You now have a working AI app with full observability built in.

What This Lets You Do

Once you have this basic setup working, you can:

Debug problems by seeing exactly what users asked and what the AI responded
Optimize costs by identifying which prompts use the most tokens
Improve quality by spotting patterns in where the AI struggles
Build confidence by actually understanding how your AI behaves in production

Why This Matters for Beginners

If you're new to AI development (like I was), this approach is perfect because:

No complex setup - it's literally a few lines of code
Immediate value - you get useful insights from day one
No lock-in - you can remove the Langfuse import anytime
It grows with you - as your app gets more complex, the observability keeps up

I've published the complete example on GitHub with a more full-featured demo:

Gaia + Langfuse Example Repository

The repo includes better error handling, more examples, and instructions for common scenarios.

Building AI Agents with Haystack and Gaia Node: A Practical Guide

Harish Kotra (he/him) — Wed, 27 Aug 2025 04:48:00 +0000

In this technical blog post, I'll walk through how to build an AI agent that combines the flexibility of Haystack's agent framework with the privacy benefits of self-hosted LLMs through Gaia Node.

This solution gives you the best of both worlds: sophisticated tool-using capabilities with complete control over your infrastructure.

What We're Building

Our example creates an AI agent that can answer questions about current information by:

Using a self-hosted LLM via Gaia Node for processing
Performing real-time web searches when needed
Providing summarized, accurate responses based on the latest information

The agent specifically handles queries like:

"How is the weather in Berlin?"
"What are the latest news headlines?"
"Tell me about recent events in technology"

Technical Architecture

Components Overview

Our solution leverages three main components:

Haystack: An open-source framework for building production-ready LLM applications
Gaia Node: A self-hosted inference server for open-source LLMs
SerperDev: A search API for obtaining real-time web information

Why This Stack?

Data Privacy: All LLM processing happens on your infrastructure
Cost Control: No per-token pricing, just hardware costs
Flexibility: Choose any supported open-source model
Real-time Capabilities: Access current information via web search

Step-by-Step Implementation

1. Environment Setup

First, we install the necessary dependencies:

pip install haystack-ai python-dotenv requests

2. Configuration

We use environment variables for secure configuration:

# .env file
GAIA_API_KEY=your_gaia_node_api_key
GAIA_NODE_URL=http://localhost:8080/v1
GAIA_MODEL_NAME=llama3b
SERPERDEV_API_KEY=your_serperdev_api_key

3. Core Code Implementation

Here's the complete implementation:

import os
from haystack.components.agents import Agent
from haystack.tools.component_tool import ComponentTool
from haystack.components.websearch import SerperDevWebSearch
from haystack.dataclasses import ChatMessage
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.utils import Secret
from dotenv import load_dotenv

load_dotenv()

# Create the web search component
web_search = SerperDevWebSearch(
    api_key=Secret.from_env_var("SERPERDEV_API_KEY"), 
    top_k=3
)

# Create the ComponentTool
web_tool = ComponentTool(
    component=web_search,
    name="web_search",
    description="Use this tool to search the web for current information like weather, news, or facts. Always use this tool when asked about current information."
)

# Configure Gaia Node connection
chat_generator = OpenAIChatGenerator(
    api_key=Secret.from_env_var("GAIA_API_KEY"),
    api_base_url=os.getenv("GAIA_NODE_URL"),
    model=os.getenv("GAIA_MODEL_NAME", "llama3b")
)

# Create the agent with the web tool
tool_calling_agent = Agent(
    chat_generator=chat_generator,
    system_prompt="""You are a helpful agent with web search capabilities. 
                     When asked about current information (weather, news, facts, real-time data),
                     ALWAYS use the web_search tool first.
                     After getting results, extract relevant information and present it clearly.
                     If search results are incomplete, mention this but still provide the best available information.""",
    tools=[web_tool]
)

# Run the agent
try:
    user_message = ChatMessage.from_user("How is the weather in Berlin today?")
    result = tool_calling_agent.run(messages=[user_message])

    response = result["messages"][-1].text
    print(f"Agent Response: {response}")

except Exception as e:
    print(f"Error: {e}")

Key Technical Concepts

1. Haystack Agents Framework

Haystack's agent system provides a structured way to build LLM-powered applications that can use tools. The agent:

Receives a user query
Decides whether to use tools
Processes the tool results
Generates a final response

2. Gaia Node Integration

Gaia Node provides an OpenAI-compatible API endpoint for self-hosted models. This compatibility makes it easy to integrate with existing frameworks like Haystack that support OpenAI models.

3. Tool Calling Pattern

The tool calling pattern is fundamental to building capable AI agents:

The LLM decides when a tool is needed
The tool executes and returns results
The LLM incorporates these results into its response

Advanced Features and Customization

Adding Memory

To create conversational agents, you can add memory:

from haystack.components.agents.memory import ConversationMemory

memory = ConversationMemory()
agent_with_memory = Agent(
    chat_generator=chat_generator,
    system_prompt=system_prompt,
    tools=[web_tool],
    memory=memory
)

Multiple Tools

Agents can use multiple tools for different purposes:

# Example: Adding a calculator tool
from haystack.tools.predefined import CalculatorTool

calculator_tool = CalculatorTool()
agent = Agent(
    chat_generator=chat_generator,
    tools=[web_tool, calculator_tool],
    system_prompt="You can both search the web and perform calculations."
)

Custom Tools

You can create custom tools for specific needs:

from haystack.tools import tool

@tool
def database_lookup(query: str):
    """Look up information in our internal database."""
    # Implementation here
    return results

Deployment Considerations

Infrastructure Requirements

Running this stack requires:

A server with sufficient RAM/CPU for your chosen model
Network access for web search APIs
Secure storage for API keys and credentials

Performance Optimization

Use model quantization for faster inference
Implement caching for frequent queries
Consider batch processing for high-volume applications

Real-World Applications

This pattern can be adapted for various use cases:

Customer Support: Answer questions based on internal documentation + web search
Research Assistance: Gather and summarize information from multiple sources
Internal Knowledge Management: Combine internal data with external context

Combining Haystack with Gaia Node creates a powerful foundation for building AI applications that respect data privacy while maintaining sophisticated capabilities. The agent pattern demonstrated here provides a flexible framework that can be extended with additional tools, custom logic, and domain-specific knowledge.

This approach is particularly valuable for organizations that:

Handle sensitive data
Require cost-effective AI solutions
Need custom model behavior
Want to avoid vendor lock-in

Get Started

Ready to build your own AI agent with Haystack and Gaia Node? Check out the complete example and documentation in the Gaia Cookbook:

🔗 Gaia Cookbook - Haystack Integration

Reimagining Web3 Interactions: How Gaia Powers Smart Token Creation on Linea with MetaMask Delegation Toolkit

Sushmita - aka meowy — Tue, 26 Aug 2025 13:31:59 +0000

It was only a matter of time before AI Agents and web3 joined forces, creating a more accessible and democratic user experience. For years there was a strong technical barrier that stood as a fortress wall for users, but now AI agents are acting as a skilled guide, interpreting complex protocols with simple chat conversations and intuitive responses. There’s always sophisticated web3 technology advancement happening, but how we engage with these protocols with a layer of intelligence that adapts with our natural communication pattern with AI, rather than forcing us to adapt with the technical barrier, is what makes artificial intelligence so important. In this blog post, we will go over how to implement MetaMask Delegation Toolkit with Gaia to perform smart contract operations like the token creation process.

Web3 UX: Still a challenge for users

Even though there’s a huge potential for blockchain technology, one challenge that still remains is user experience. Creating and deploying a token on any L1/L2/altVM blockchain requires specialized knowledge of writing smart contract in programming languages like solidity, Rust, Sway, Vyper and even new languages like Cairo and there’s also the complex deployment process. Even for experienced developers, the specified process can be time-consuming. We also have to consider the fact that smart contracts can also contain vulnerabilities which can result in potential fund loss.

Let’s take a look at what it typically takes to create a simple ERC20 token:

Write Smart Contract code for the token contract
Compile the code with the correct and specific compiler version
Deploy the smart contract to a testnet for verification.
Configure gas settings to make sure of the successful deployment
Deploy to the contract to mainnet while managing private keys securely
Verify the contract on block explorers (so that it’s not an unverified token contract)

For an average user, this barrier can be quite the challenge, which ultimately limits the participation in one of the most basic activities in the web3 ecosystem - creating tokens. This is where the combination of AI and smart wallet like delegation technology offers an amazing solution.

Understanding the MetaMask Delegation Toolkit

The MetaMask Delegation Toolkit (DTK) introduces a paradigm shift in how permissions can be granted on the blockchain through AI. At its heart, DTK enables a security model where one account (the delegator) can authorize another account (the delegate) to perform specific actions on its behalf, with fine-grained control over what those actions can be.

The DTK operates through several key components that work together to create a secure delegation system:

1. Smart Accounts

Smart accounts are contract-based accounts that can enforce rules and permissions beyond what traditional EOA (Externally Owned Accounts) can do. These accounts are the foundation of the delegation system.

In this implementation, two smart accounts are created:

// Creating a smart account for the user (delegator)
const delegatorSmartAccount = await toMetaMaskSmartAccount({
  client: publicClient,  // Connection to the blockchain
  implementation: Implementation.Hybrid,  // Account implementation type
  deployParams: [address, [], [], []],  // Parameters for account initialization
  deploySalt: createSalt(),  // Unique identifier for deterministic deployment
  signatory: { walletClient },  // Connection to user's wallet for signing
});

// Creating a smart account for Gaia (delegate)
const aiPrivateKey = generatePrivateKey();  // Generate a new private key for the AI
const aiAccount = privateKeyToAccount(aiPrivateKey);  // Create an EOA from the private key

const aiSmartAccount = await toMetaMaskSmartAccount({
  client: publicClient,
  implementation: Implementation.Hybrid,
  deployParams: [aiAccount.address, [], [], []],
  deploySalt: createSalt(),
  signatory: { account: aiAccount },  // AI's account will sign its transactions
});

These accounts are "counterfactual" - they exist with deterministic addresses before they're actually deployed on the blockchain. This allows for gas-efficient operation as the accounts only get deployed when they first perform a transaction.

2. Delegations with Caveats

A delegation is a cryptographically signed permission grant that specifies what actions are allowed. Caveats are restrictions that define the precise boundaries of what a delegate can do.
The implementation of caveats is where the real security magic happens:

// Define strict boundaries for what Gaia can do
const caveats = createCaveatBuilder(delegatorAccount.environment)
  // Only allow interaction with our factory contract
  .addCaveat("allowedTargets", [FACTORY_CONTRACT_ADDRESS])
  // Prevent ETH spending entirely
  .addCaveat("valueLte", BigInt(0))
  // Only allow calling the createToken function
  .addCaveat("allowedMethods", [CREATE_TOKEN_SELECTOR]);

// Create the delegation with these restrictions
const newDelegation = createRootDelegation(
  aiDelegateAccount.address,  // Who receives permission (Gaia)
  delegatorAccount.address,   // Who grants permission (User)
  caveats,                    // The restrictions
  BigInt(createSalt())        // Unique identifier
);

// Sign the delegation with the user's account
const signature = await delegatorAccount.signDelegation({
  delegation: newDelegation
});

This code creates a delegation that:

Restricts AI to interact only with the specified factory contract address
Prevents AI from spending any of the user's ETH (value limit set to zero)
Allows AI to call only the createToken function on that contract

These restrictions create a secure sandbox that protects the user's assets while enabling specific functionality. Think of it as giving someone a limited power of attorney to perform only one very specific action on your behalf, rather than handing over full control of your assets.

3. Delegation Storage and Persistence

For the delegation system to be useful across sessions, AI stores the delegation information securely using the DTK's delegation storage service:

// Store a delegation in the service
const delegationStorageClient = new DelegationStorageClient({
  apiKey: process.env.NEXT_PUBLIC_DELEGATION_STORAGE_API_KEY!,
  apiKeyId: process.env.NEXT_PUBLIC_DELEGATION_STORAGE_API_KEY_ID!,
  environment: DelegationStorageEnvironment.dev,
});

// Store the delegation in the delegation storage service
const storedDelegation = await delegationStorageClient.storeDelegation(signedDelegation);

This storage system allows delegations to persist beyond browser sessions, enabling users to return to the application and have AI retain its permissions without repeating the setup process.

Gaia: The Decentralized AI Infrastructure

Now that we understand the delegation framework, let's examine how Gaia’s Public Models utilizes these delegations to deploy tokens based on natural language requests using API.
AI is integrated into the application through a chat interface where users can describe the token they want to create. The agent processes these descriptions, extracts the key parameters, and then executes the token creation through the delegation system.

The AI Tool for Token Deployment

The bridge between agents natural language understanding and blockchain execution is implemented as a custom AI tool.
Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. I’ve used vercel’s AI sdk to get started with tools.

Let’s break down the code from here.

// Delegation Storage Singleton
let delegationStorageInstance: DelegationStorageClient | null = null;


// Helper function to log storage configuration
const logStorageConfig = (apiKey?: string, apiKeyId?: string) => {
 console.group("=== Delegation Storage Configuration ===");
 console.log("API Key format check:", {
   exists: !!apiKey,
   length: apiKey?.length,
   firstChars: apiKey?.substring(0, 4),
   lastChars: apiKey?.substring(apiKey.length - 4),
   hasSpecialChars: apiKey?.match(/[^a-zA-Z0-9]/) ? true : false,
 });
 console.log("API Key ID format check:", {
   exists: !!apiKeyId,
   length: apiKeyId?.length,
   firstChars: apiKeyId?.substring(0, 4),
   lastChars: apiKeyId?.substring(apiKeyId.length - 4),
   hasSpecialChars: apiKeyId?.match(/[^a-zA-Z0-9]/) ? true : false,
 });
 console.log("Environment:", DelegationStorageEnvironment.dev);
 console.log(
   "Running on:",
   typeof window !== "undefined" ? "client" : "server"
 );
 console.groupEnd();
};


/**
* Gets the delegation storage client, initializing it if necessary
* @returns A configured DelegationStorageClient instance
*/
export const getDelegationStorageClient = (): DelegationStorageClient => {
 if (!delegationStorageInstance) {
   const apiKey = process.env.NEXT_PUBLIC_DELEGATION_STORAGE_API_KEY;
   const apiKeyId = process.env.NEXT_PUBLIC_DELEGATION_STORAGE_API_KEY_ID;


   logStorageConfig(apiKey, apiKeyId);


   if (!apiKey || !apiKeyId) {
     throw new Error("Delegation storage API key and key ID are required");
   }


   try {
     delegationStorageInstance = new DelegationStorageClient({
       apiKey,
       apiKeyId,
       environment: DelegationStorageEnvironment.dev,
       fetcher:
         typeof window !== "undefined" ? window.fetch.bind(window) : undefined,
     });
     console.log("DelegationStorageClient initialized successfully");
   } catch (error) {
     console.error("Error creating DelegationStorageClient:", error);
     throw error;
   }
 }
 return delegationStorageInstance;
};


/**
* Stores a delegation in the delegation storage service
* @param delegation The delegation to store
* @returns The result of the store operation
*/
export const storeDelegation = async (delegation: DelegationStruct) => {
 try {
   console.group("=== Storing Delegation ===");
   console.log("Delegation details:", {
     delegate: delegation.delegate,
     delegator: delegation.delegator,
     hasSignature: !!delegation.signature,
     salt: delegation.salt.toString(),
   });


   const delegationStorageClient = getDelegationStorageClient();
   const result = await delegationStorageClient.storeDelegation(delegation);


   console.log("Delegation stored successfully:", result);
   console.groupEnd();
   return result;
 } catch (error: any) {
   console.error("Delegation storage error:", {
     name: error.name,
     message: error.message,
     status: error.status,
     details: error.details,
     stack: error.stack,
   });
   console.groupEnd();
   throw error;
 }
};


/**
* Retrieves a delegation chain by its hash
* @param hash The hash of the delegation chain to retrieve
* @returns The delegation chain
*/
export const getDelegationChain = async (hash: Hex) => {
 try {
   console.log("Fetching delegation chain for hash:", hash);
   const delegationStorageClient = getDelegationStorageClient();
   const result = await delegationStorageClient.getDelegationChain(hash);
   console.log("Delegation chain fetched:", result);
   return result;
 } catch (error) {
   console.error("Error fetching delegation chain:", error);
   throw error;
 }
};


/**
* Fetches delegations for a specific address
* @param address The address to fetch delegations for
* @param filter Whether to fetch given or received delegations
* @returns The delegations for the address
*/
export const fetchDelegations = async (
 address: Hex,
 filter: DelegationStoreFilter
) => {
 try {
   console.log(
     "Fetching delegations for address:",
     address,
     "filter:",
     filter
   );
   const delegationStorageClient = getDelegationStorageClient();
   const result = await delegationStorageClient.fetchDelegations(
     address,
     filter
   );
   console.log("Delegations fetched:", result);
   return result;
 } catch (error) {
   console.error("Error fetching delegations:", error);
   throw error;
 }
};


/**
* Gets delegation info from session storage (if available)
* @returns The delegation info or null if not found
*/
export const getDelegationInfoFromSession = () => {
 if (typeof window === "undefined") return null;


 try {
   const delegationInfoStr = sessionStorage.getItem("aiDelegateInfo");
   if (!delegationInfoStr) return null;


   return JSON.parse(delegationInfoStr);
 } catch (error) {
   console.error("Error retrieving delegation info from session:", error);
   return null;
 }
};


/**
* Gets the full delegation from session storage (if available)
* @returns The full delegation or null if not found
*/
export const getFullDelegationFromSession = () => {
 if (typeof window === "undefined") return null;


 try {
   const delegationStr = sessionStorage.getItem("delegation");
   if (!delegationStr) return null;


   const delegation = JSON.parse(delegationStr);


   // Convert string salt back to BigInt
   if (delegation && typeof delegation.salt === "string") {
     delegation.salt = BigInt(delegation.salt);
   }


   return delegation;
 } catch (error) {
   console.error("Error retrieving delegation from session:", error);
   return null;
 }
};


/**
* Clears delegation info from session storage
*/
export const clearDelegationSession = () => {
 if (typeof window === "undefined") return;


 sessionStorage.removeItem("aiDelegateInfo");
 sessionStorage.removeItem("delegation");
 sessionStorage.removeItem("aiDelegatePrivateKey");
};



const createTokenTool = createTool({""});


export const tools = {
 createToken: createTokenTool,
};

this tool encapsulates all the complexity of token deployment. When the AI determines that the user wants to create a token, it invokes this tool with the appropriate parameters extracted from the conversation.

The Token Factory Contract: Writing the smart contract for the Agent

The ERC20 Factory contract that Gaia interacts with is designed to create new token instances based on the provided parameters:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "./BaseERC20Token.sol";

contract ERC20Factory {
    address public owner;
    mapping(address => bool) public tokenExists;
    address[] public allTokens;

    event TokenCreated(
        address indexed tokenAddress,
        string name,
        string symbol,
        uint256 initialSupply,
        address owner
    );

    constructor() {
        owner = msg.sender;
    }

    function createToken(
        string memory name,
        string memory symbol,
        uint256 initialSupply
    ) external returns (address) {
        BaseERC20Token newToken = new BaseERC20Token(
            name,
            symbol,
            initialSupply,
            msg.sender
        );

        address tokenAddress = address(newToken);
        tokenExists[tokenAddress] = true;
        allTokens.push(tokenAddress);

        emit TokenCreated(
            tokenAddress,
            name,
            symbol,
            initialSupply,
            msg.sender
        );

        return tokenAddress;
    }

    function getAllTokens() external view returns (address[] memory) {
        return allTokens;
    }

    function getTokenCount() external view returns (uint256) {
        return allTokens.length;
    }
}

The base ERC20 token that gets created:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract BaseERC20Token is ERC20, Ownable {
    constructor(
        string memory name,
        string memory symbol,
        uint256 initialSupply,
        address owner
    ) ERC20(name, symbol) Ownable(owner) {
        _mint(owner, initialSupply * (10 ** decimals()));
    }
}

This factory pattern provides several benefits:

The base token implementation is fixed and secure
Each token is customized through constructor parameters
The factory maintains a registry of all created tokens
Deployment is gas-efficient

You can check the whole smart contract code here: https://github.com/meowyx/erc20-factory

The User Experience: From Conversation to Blockchain

What makes AI special is how it transforms a complex blockchain operation into a simple conversation. Let's explore the user experience of interacting with AI to create tokens.

The Chat Interface

The chat interface is where users interact with Gaia through natural language:

export const Chat = () => {
  const { address } = useAccount();
  const [delegationEnabled, setDelegationEnabled] = useState(false);

  // Check if delegation is set up
  useEffect(() => {
    const checkDelegation = () => {
      const delegateInfo = sessionStorage.getItem('aiDelegateInfo');
      setDelegationEnabled(!!delegateInfo);
    };

    checkDelegation();
    window.addEventListener('storage', checkDelegation);

    return () => {
      window.removeEventListener('storage', checkDelegation);
    };
  }, []);

  const { messages, input, handleInputChange, handleSubmit, isLoading } =
    useChat({
      initialMessages: [
        {
          role: "system",
          content: `You have connected your wallet successfully. Your wallet address is ${address}. ${
            delegationEnabled
              ? "You have delegated token creation permissions to me. I can deploy ERC20 tokens on your behalf through a factory contract. Just ask me to create a token and specify the name, symbol, and initial supply."
              : "You can delegate token creation permissions to me using the delegation manager above. Once set up, I'll be able to create custom ERC20 tokens for you with limited permissions."
          }`,
          id: "system",
        },
      ],
    });

  // Render chat interface and handle responses
  return (
    <div className="h-full w-full space-y-4 max-w-3xl">
      <div className="border h-full max-h-96 rounded-md p-4 space-y-6 justify-end overflow-y-scroll">
        {messages.map((message) => (
          <div key={message.id}>
            {/* Render user and AI messages */}
            {message.role === "user" ? (
              <div className="flex w-full justify-start">
                <div className="w-fit max-w-md bg-gray-800 text-gray-50 rounded-md p-2">
                  <strong>User:</strong> {message.content}
                </div>
              </div>
            ) : (
              <div className="flex w-full justify-end">
                <div className="w-fit max-w-md bg-gray-100 text-gray-900 rounded-md p-2">
                  <strong>AI:</strong> {message.content}
                </div>
              </div>
            )}

            {/* Handle tool invocation results */}
            <div>
              {message.toolInvocations?.map((toolInvocation) => {
                const { toolName, toolCallId, state } = toolInvocation;
                if (state === "result" && toolName === "deployERC20") {
                  const { result } = toolInvocation;
                  return (
                    <div key={toolCallId} className="p-3 my-2 rounded">
                      {result.success ? (
                        <div className="bg-green-50 border border-green-200 p-3 rounded">
                          <h3 className="font-bold text-green-800">Token Deployed Successfully!</h3>
                          <div className="mt-2 space-y-1">
                            <p><strong>Name:</strong> {result.tokenName}</p>
                            <p><strong>Symbol:</strong> {result.tokenSymbol}</p>
                            <p><strong>Address:</strong> {result.tokenAddress}</p>
                            <p className="mt-2">
                              <a
                                href={`https://sepolia.etherscan.io/tx/${result.transactionHash}`}
                                target="_blank"
                                className="text-blue-600 underline"
                              >
                                View transaction on Etherscan
                              </a>
                            </p>
                          </div>
                        </div>
                      ) : (
                        <div className="bg-red-50 border border-red-200 p-3 rounded">
                          <h3 className="font-bold text-red-800">Token Deployment Failed</h3>
                          <p className="text-red-700 mt-1">
                            {result.error}
                          </p>
                        </div>
                      );
                    </div>
                  );
                }
              })}
            </div>
          </div>
        ))}
      </div>

      <form className="flex gap-3" onSubmit={handleSubmit}>
        <Input
          value={input}
          onChange={handleInputChange}
          placeholder="Type a message..."
        />
        <Button type="submit">Send</Button>
      </form>
    </div>
  );
};

Complete Flow: From User Request to Token Deployment

The entire process flows through these steps:

User Connects Wallet: The application detects the connected wallet and displays the Delegation Manager.
Initial Setup: The user clicks "Set Up Delegation Accounts", which creates two smart accounts and prepares for delegation.
Delegation Creation: The user clicks "Create Delegation with Restrictions", which grants Gaia limited permissions to deploy tokens.
Natural Language Interaction: The user types a request like: "Please create a token called Community Rewards Token with symbol CRT and an initial supply of 10000 tokens."
AI Processing: AI processes this request, recognizing it as a token creation instruction and extracting the key parameters.
Tool Invocation: AI invokes the deployERC20Tool with the extracted parameters (name, symbol, supply).
Delegation Redemption: The tool:
- Retrieves AI's account information and the delegation
- Encodes a call to the createToken function with the specified parameters
- Wraps this call in a delegation redemption that proves Gaia has permission
- Submits the transaction as a user operation through a bundler
On-Chain Execution:
- The bundler verifies the delegation and that the action is allowed by the caveats
- The factory contract creates a new ERC20 token with the specified parameters
- The transaction is confirmed and a TokenCreated event is emitted
Result Display: AI presents the results to the user, including:
- Confirmation of successful deployment
- The token name, symbol, and contract address

This entire process happens without the user needing to understand the underlying smart contract interactions, gas optimization, or transaction signing. They simply express what they want in natural language, and Gaia handles the rest.

The Technical Magic: How It Really Works

To fully understand this system, let's dig deeper into the technical mechanisms that make it possible.

Account Abstraction (ERC-4337)

The foundation of the delegation system is ERC-4337, the Account Abstraction standard. This separates transaction signing from transaction payment and execution, making more flexible account models.

In traditional Ethereum transactions, the account that signs a transaction must also pay for gas and must be the one executing the transaction. Account abstraction breaks these dependencies apart, enabling:

Separate accounts for signing, paying, and executing
More complex validation logic beyond simple signature verification
Batching of multiple actions into a single transaction
Gas sponsorship and alternative payment methods

Gaia leverages account abstraction through the bundler client:

// Send a user operation instead of a regular transaction
const userOpHash = await bundlerClient.sendUserOperation({
  account: aiSmartAccount,
  calls: [
    {
      to: aiSmartAccount.address,
      data: redeemDelegationCalldata,
    },
  ],
});

This approach allows AI to act as a delegate without requiring the user to send their private keys or pre-sign transactions. Instead, the delegation itself serves as the authorization.

The Function Selector: A Critical Security Boundary

One of the most important security aspects of the implementation is the use of function selectors in caveats. A function selector is the first 4 bytes of the keccak256 hash of a function signature, uniquely identifying that function.

For the factory's createToken function, the selector is calculated as:

keccak256("createToken(string,string,uint256)").substring(0, 10)
// Results in something like: "0x45ba7a0f"

This selector is used in the caveats to ensure Gaia can only call this specific function:

.addCaveat("allowedMethods", [CREATE_TOKEN_SELECTOR])

This is a critical security boundary because even if AI (or an attacker who somehow gained control of Gaia's private key) tried to call a different function on the target contract, the delegation system would reject the transaction as unauthorized.

Counterfactual Accounts: Efficiency Through Delayed Deployment

The smart accounts used in the system are "counterfactual" - they exist with predictable addresses before they're actually deployed on the blockchain. This is achieved through a technique called "CREATE2" that allows contracts to be deployed to deterministic addresses.

The benefits of this approach include:

Gas Efficiency: Accounts are only deployed when they first transact, saving deployment costs if they're never used.
Predictable Addresses: You can know an account's address before it's deployed, enabling references to it in other contracts.
Just-in-Time Deployment: Accounts can be deployed as part of the first transaction that uses them, simplifying the user experience.

This functionality is encapsulated in the toMetaMaskSmartAccount function, which creates accounts with deterministic addresses based on the deployment parameters and salt.

The interaction of AI agents with smart account/delegation technology shows a different approach of human interaction with blockchain. By allowing users to express their intentions in natural language while maintaining strict security boundaries, systems like Gaia can help bridge the gap between Web3's capabilities and mainstream adoption. This approach doesn't just make existing processes easier—it enables entirely new patterns of interaction that would be impossible with traditional interfaces. The combination of AI and delegation technology is just beginning to reveal its potential. There are more exciting directions could be taken in the future, for example: multi-chain operation, conditional multi-delegations, AI governance and even collaborative creation of tokens or other smart contract functionalities.

Some Resources:

The Code: https://github.com/meowyx/metamask-gaia-starter

Gaia Docs: https://docs.gaianet.ai/intro

Happy Coding 🚀

Creating Wikipedia Search Embeddings with a Gaia Node

Harish Kotra (he/him) — Tue, 26 Aug 2025 10:19:00 +0000

This tutorial shows how to create embeddings from Wikipedia articles using Gaia nodes. We'll download articles about the 2022 Olympics, split them into sections, and create embeddings using Gaia's OpenAI-compatible API.

Overview

Collect Wikipedia articles about 2022 Olympics
Split documents into searchable chunks
Create embeddings using your own Gaia node
Store results in a CSV file

Prerequisites

Install required packages:

pip install mwclient mwparserfromhell pandas tiktoken openai

Code

Here's the complete code that implements the workflow:

import mwclient
import mwparserfromhell
import os
import pandas as pd
import re
import tiktoken
from openai import OpenAI

# Configure constants
GAIA_NODE_URL = "https://llama8b.gaia.domains/v1/"
CATEGORY_TITLE = "Category:2022 Winter Olympics"
WIKI_SITE = "en.wikipedia.org"
MAX_TOKENS = 1600
BATCH_SIZE = 50

# Initialize OpenAI client with Gaia endpoint 
client = OpenAI(base_url=GAIA_NODE_URL, api_key="not-needed")

SECTIONS_TO_IGNORE = [
    "See also", "References", "External links", "Further reading", 
    "Footnotes", "Bibliography", "Sources", "Citations", "Literature",
    "Notes and references", "Photo gallery", "Works cited", "Photos",
    "Gallery", "Notes", "References and sources", "References and notes",
]

def titles_from_category(category: mwclient.listing.Category, max_depth: int) -> set[str]:
    """Get all page titles from a Wikipedia category and its subcategories."""
    titles = set()
    for cm in category.members():
        if type(cm) == mwclient.page.Page:
            titles.add(cm.name)
        elif isinstance(cm, mwclient.listing.Category) and max_depth > 0:
            deeper_titles = titles_from_category(cm, max_depth=max_depth - 1)
            titles.update(deeper_titles)
    return titles

def all_subsections_from_section(section: mwparserfromhell.wikicode.Wikicode, 
                               parent_titles: list[str], 
                               sections_to_ignore: set[str]) -> list[tuple[list[str], str]]:
    """Extract all subsections from a Wikipedia section."""
    headings = [str(h) for h in section.filter_headings()]
    title = headings[0]
    if title.strip("=" + " ") in sections_to_ignore:
        return []
    titles = parent_titles + [title]
    full_text = str(section)
    section_text = full_text.split(title)[1]
    if len(headings) == 1:
        return [(titles, section_text)]
    else:
        first_subtitle = headings[1]
        section_text = section_text.split(first_subtitle)[0]
        results = [(titles, section_text)]
        for subsection in section.get_sections(levels=[len(titles) + 1]):
            results.extend(all_subsections_from_section(subsection, titles, sections_to_ignore))
        return results

def all_subsections_from_title(title: str,
                             sections_to_ignore: set[str] = SECTIONS_TO_IGNORE,
                             site_name: str = WIKI_SITE) -> list[tuple[list[str], str]]:
    """Get all subsections from a Wikipedia page title."""
    site = mwclient.Site(site_name)
    page = site.pages[title]
    text = page.text()
    parsed_text = mwparserfromhell.parse(text)
    headings = [str(h) for h in parsed_text.filter_headings()]
    if headings:
        summary_text = str(parsed_text).split(headings[0])[0]
    else:
        summary_text = str(parsed_text)
    results = [([title], summary_text)]
    for subsection in parsed_text.get_sections(levels=[2]):
        results.extend(all_subsections_from_section(subsection, [title], sections_to_ignore))
    return results

def clean_section(section: tuple[list[str], str]) -> tuple[list[str], str]:
    """Clean up a Wikipedia section by removing references and whitespace."""
    titles, text = section
    text = re.sub(r"<ref.*?</ref>", "", text)
    text = text.strip()
    return (titles, text)

def keep_section(section: tuple[list[str], str]) -> bool:
    """Determine if a section should be kept based on length."""
    titles, text = section
    return len(text) >= 16

def num_tokens(text: str) -> int:
    """Count the number of tokens in a text."""
    encoding = tiktoken.encoding_for_model("gpt-4")
    return len(encoding.encode(text))

def halved_by_delimiter(string: str, delimiter: str = "\n") -> list[str]:
    """Split a string in two parts at a delimiter, balancing tokens."""
    chunks = string.split(delimiter)
    if len(chunks) == 1:
        return [string, ""]
    elif len(chunks) == 2:
        return chunks
    else:
        total_tokens = num_tokens(string)
        halfway = total_tokens // 2
        best_diff = halfway
        for i, chunk in enumerate(chunks):
            left = delimiter.join(chunks[: i + 1])
            left_tokens = num_tokens(left)
            diff = abs(halfway - left_tokens)
            if diff >= best_diff:
                break
            else:
                best_diff = diff
        left = delimiter.join(chunks[:i])
        right = delimiter.join(chunks[i:])
        return [left, right]

def split_strings_from_subsection(subsection: tuple[list[str], str],
                                max_tokens: int = 1000,
                                max_recursion: int = 5) -> list[str]:
    """Split a subsection into smaller pieces that fit within max_tokens."""
    titles, text = subsection
    string = "\n\n".join(titles + [text])
    if num_tokens(string) <= max_tokens:
        return [string]
    elif max_recursion == 0:
        return [string[:max_tokens]]
    else:
        titles, text = subsection
        for delimiter in ["\n\n", "\n", ". "]:
            left, right = halved_by_delimiter(text, delimiter=delimiter)
            if left == "" or right == "":
                continue
            else:
                results = []
                for half in [left, right]:
                    half_subsection = (titles, half)
                    half_strings = split_strings_from_subsection(
                        half_subsection,
                        max_tokens=max_tokens,
                        max_recursion=max_recursion - 1,
                    )
                    results.extend(half_strings)
                return results
    return [string[:max_tokens]]

def main():
    # 1. Collect Wikipedia articles
    site = mwclient.Site(WIKI_SITE)
    category_page = site.pages[CATEGORY_TITLE]
    titles = titles_from_category(category_page, max_depth=1)
    print(f"Found {len(titles)} articles")

    # 2. Extract and clean sections
    wikipedia_sections = []
    for title in titles:
        wikipedia_sections.extend(all_subsections_from_title(title))
    print(f"Found {len(wikipedia_sections)} sections")

    wikipedia_sections = [clean_section(ws) for ws in wikipedia_sections]
    wikipedia_sections = [ws for ws in wikipedia_sections if keep_section(ws)]

    # 3. Split into chunks
    wikipedia_strings = []
    for section in wikipedia_sections:
        wikipedia_strings.extend(split_strings_from_subsection(section, max_tokens=MAX_TOKENS))
    print(f"Split into {len(wikipedia_strings)} chunks")

    # 4. Get embeddings with retries
    embeddings = []
    for batch_start in range(0, len(wikipedia_strings), BATCH_SIZE):
        batch_end = batch_start + BATCH_SIZE
        batch = wikipedia_strings[batch_start:batch_end]
        print(f"Processing batch {batch_start} to {batch_end-1}")

        max_retries = 3
        for attempt in range(max_retries):
            try:
                response = client.embeddings.create(
                    model="nomic-embed",
                    input=batch
                )
                batch_embeddings = [e.embedding for e in response.data]
                embeddings.extend(batch_embeddings)
                break
            except Exception as e:
                print(f"Error on attempt {attempt + 1}: {str(e)}")
                if attempt == max_retries - 1:
                    raise
                import time
                time.sleep(5 * (attempt + 1))  # Exponential backoff

    # 5. Save to CSV
    df = pd.DataFrame({"text": wikipedia_strings, "embedding": embeddings})
    df.to_csv("winter_olympics_2022.csv", index=False)
    print("Saved embeddings to winter_olympics_2022.csv")

if __name__ == "__main__":
    main()

How It Works

Document Collection: Downloads Wikipedia articles from the "2022 Winter Olympics" category.
Text Processing:
- Splits articles into sections
- Removes references and cleans text
- Excludes short sections and irrelevant parts like "References"
- Splits long sections to fit token limits
Embedding Generation:
- Uses Gaia's OpenAI-compatible endpoint
- Processes text in small batches (50 chunks)
- Includes retry logic for reliability
- Uses the nomic-embed model
Storage: Saves text chunks and their embeddings to a CSV file.

Usage

Save the code as wikipedia_embeddings.py and run:

python wikipedia_embeddings.py

The script will create a CSV file containing text chunks and their embeddings, which can be used for semantic search or other applications.

Key Features

OpenAI-compatible API usage
Robust error handling with retries
Efficient text chunking
Clean Wikipedia text processing
Token-aware splitting

Notes

The script uses public Gaia nodes - no API key needed
Adjust BATCH_SIZE if you encounter timeouts
The embeddings CSV can be large - ensure sufficient disk space
The process may take several minutes depending on article count

You can find ready-to-use Gaia nodes at Public Nodes from Gaia.

Credits

Inspired from OpenAI's Cookbook

DEV Community: Gaia

Building Stateful vs. Stateless AI Agents: A Deep Dive with Gaia Nodes and Supermemory

The Stack

The Architecture

The Code

Prerequisites

The Logic (app.py)

The "Memory Paradox": When RAG Goes Wrong

The Experiment: The Blue Pineapple

1. The Naive Approach (The Bad)

2. The Solution: Direct Injection & Strict Prompting (The Good)

The Results

Technical Challenges & Solutions

1. Gaia Node Streaming

2. Supermemory Result Parsing

Conclusion

Boost Your Local AI: Supercharge Gaia Nodes with Redis for Speed & Memory

Why Redis for AI with Gaia?

Example 1: Basic Gaia Node & Redis Integration

What We'll Do:

What It Looks Like:

What It Does:

Key Takeaway:

Example 2: Intermediate - Caching Gaia Node Responses

What We'll Do:

What It Looks Like:

What It Does:

Key Takeaway:

Combining Gaia Nodes, Camino AI, and Tavily for Enterprise-grade Location Awareness

What We're Building

Technical Architecture

Prerequisites

Environment Setup

Core Implementation

Multi-AI Client Integration

Intelligent Tool Routing

Key Features

1. Intelligent Query Routing

2. Advanced Spatial Reasoning

3. Specialized Sub-agents

4. Comparative Analysis Engine

Enterprise Use Cases

1. Commercial Real Estate Analysis

2. Supply Chain Optimization

3. Market Expansion Planning

Performance Architecture

Multi-tier Processing

Intelligent Caching

Security Considerations

Data Privacy Architecture

Access Control

Example Output

Building an AI-Powered Web3 Voting DApp with Gaia

The Vision: Democracy Should Be Conversational

Why Gaia? Decentralized AI for Web3

True Decentralization

Tool-Calling Capabilities

Blockchain-Native Design

Architecture: Where AI Meets Smart Contracts

Frontend Layer

AI Integration Layer

Blockchain Layer

Natural Language Commands That Work

Creating Votes

Viewing Results

Casting Votes

Technical Deep Dive: AI Tools for Blockchain

Setting Up Your Own Gaia Node

Real-World Impact: Making Web3 Accessible

Non-Technical Users

Rapid Prototyping

Educational Value

Challenges Solved and Lessons Learned

State Management Complexity

Natural Language Ambiguity

Transaction Feedback

Performance and Scalability

Future Enhancements

Knowledge Base Integration

Multi-Chain Support

The Logic (`app.py`)