Hyphae Setup Guide

Welcome to Hyphae

Please read Get Started with Truffle before continuing with this tutorial.

Prerequisites

macOS Setup

Install Python 3

If you don't have Python 3 installed on your Mac, follow this comprehensive guide to install Python 3 properly.

Linux Setup

sudo apt update
sudo apt install -y python3 python3-pip
pip3 install hyphae

Windows Setup

1. Download Python from: https://www.python.org/downloads/
2. Install Python following the installer instructions
3. Open Command Prompt or PowerShell and run:

pip install hyphae

Create Virtual Environment and Install Hyphae

Once you have Python 3 installed:

python3 -m venv myenv
source ./myenv/bin/activate
pip3 install hyphae

Building Your First Hyphae App: ArXiv Research Assistant

Part 1: Understanding the Code

Open example_apps/Arxiv/arxiv.py and follow along.

The Basics: Imports and Setup

import hyphae  # The main SDK
from hyphae.tools.respond_to_user import RespondToUserReturnType
from perplexity import PerplexitySearcher  # see perplexity.py
import hyphae.hooks as hooks

Key Concept: Hyphae apps are Python classes with decorated methods that become "tools" your Truffle agent can use.

Agent State and Predicates

class ArxivApp:
    def __init__(self):
        self.selected_paper = None    # Agent remembers selected paper
        self.paper_content = None     # Cached content
        
    def has_paper_selected(self) -> bool:
        """Predicate function - controls when tools are available"""
        return self.selected_paper is not None

Key Concept: Predicates control when tools are available, allowing you to have more control over your agents use of available tools.

Tool Definitions

@hyphae.tool("Search for papers on a specific topic", icon="magnifyingglass")
@hyphae.args(
    query="The search query (topic, keywords, or title)",
    max_results="Maximum number of results to return"
)
def SearchPapers(self, query: str, max_results: int = 10) -> str:
    # Tool implementation here...

Key Concept:

• @hyphae.tool() makes a method available to your Truffle agent
• @hyphae.args() describes parameters so your agent knows how to use the tool
• Tools return strings that your agent can read and use

Workflow Design: Search → Select → Analyze

1. Search Tools (always available):

   • SearchPapers() - ArXiv API search
   • SearchWebPapers() - Perplexity search
   • SearchExternalPapers() - Semantic Scholar search

2. Selection Tool (changes agent state):

   • SelectPaper() - Stores paper data in self.selected_paper

3. Analysis Tools (only available after selection):

   • Researcher() - expert agent on analyzing academic papers
   • GetCurrentPaper() - View selected paper info

@hyphae.tool("Researcher - Discuss the selected paper", 
             predicate=lambda self: self.has_paper_selected())  # Only available when paper selected

Key Concept: Predicates create conditional tool access, guiding agents through specific workflows.

External API Integration

The app shows three different integration patterns:

1. REST API with XML/Atom (ArXiv):

def SearchPapers(self, query: str, max_results: int = 10) -> str:
    url = f"http://export.arxiv.org/api/query?search_query=all:{quote(query)}"
    response = requests.get(url)
    feed = feedparser.parse(response.content)  # Parse XML
    # Format results as markdown...

2. REST API with JSON (Semantic Scholar):

def SearchExternalPapers(self, query: str, max_results: int = 10) -> str:
    url = "https://api.semanticscholar.org/graph/v1/paper/search"
    response = requests.get(url, params=params)
    data = response.json()  # Parse JSON
    # Format results...

3. Using external models on the cloud (Perplexity):

def SearchWebPapers(self, query: str) -> str:
    search_query = f"academic papers research {query}"
    return PerplexitySearcher().run(search_query)  # Delegate to external model

See the AskForHelp tool in the Code app for another example of using other models for help:

@hyphae.tool("Researcher - Discuss the selected paper with an expert")
def Researcher(self, question: str, analysis_type: str = "general") -> str:
    # Build rich context from selected paper
    paper_info = f"""
    Paper: {self.selected_paper['title']}
    Authors: {', '.join(self.selected_paper['authors'])}
    Abstract: {self.selected_paper['abstract']}
    """
    
    # Create research prompt
    researcher_prompt = f"""You are an expert researcher. 
    User has selected this paper: {paper_info}
    
    Answer their question: {question}
    Focus on {analysis_type} analysis."""
    
    # Use external model for expert response
    return PerplexitySearcher().run(researcher_prompt)

For more detailed comments and the complete implementation, see example_apps/Arxiv/arxiv.py.

---

Part 2: Building and Deploying Your App

Now let's build and deploy this app so you can see it in action! Make sure you have hyphae installed and the TruffleOS client installed before proceeding.

Step 1: Get the Code

git clone https://github.com/deepshard/get-started-with-hyphae.git
cd get-started-with-hyphae/example_apps/Arxiv

Step 2: Understand the App Structure

Your app directory contains:

app.json - App Metadata

{
    "app_uuid": "",
    "metadata": {
        "name": "Arxiv Research Assistant",
        "description": "Truffle agent for searching and analyzing academic papers",
        "icon": "arxiv.png"
    }
}

Truffile - Container Definition

FROM hyphaehyphae/alpine-python:arm64
RUN pip3 install ddgs python-weather pytrends pandas requests feedparser 
COPY arxiv.py /opt/arxiv/arxiv.py
RUN pip3 install hyphae
WORKDIR /opt/arxiv
CMD ["python3", "/opt/arxiv/arxiv.py"]

arxiv.py - Your Agent Code

The Python file we just analyzed above.

perplexity.py - External Service Helper

Helper class for Perplexity Search integration.

Step 3: Build Your App

# Build the app into a deployable bundle
hyphae build .

This creates a .hyphae bundle file containing your containerized app.

Step 4: Deploy to TruffleOS

# Connect to your Truffle device
hyphae connect

Open your client and click accept. You are now connected. If it fails or the toast goes away, press Ctrl+C and try again.

Upload and Deploy Your App

hyphae upload .

Your app will start uploading. Go to your client to see a progress indicator. Fresh app uploading takes some time to upload, but subsequent uploads will be faster since they are cached and only update your app.

---

Part 3: Using Your App

Once deployed, users can interact with your ArXiv Research Assistant through the TruffleOS client.

Part 4: Create Your Own App

Now that you understand how Hyphae works, let's create your own app! We recommend that you read through our example apps to get more context on more hyphae features.

Step 1: Hyphae Create

# Create your new app directory
hyphae create path-to-your-app

Step 2: Customize Your App

Start building!

Step 4: Build and Deploy

# Build your app
hyphae build .

hyphae build path-to-your-app

Deploy to TruffleOS

# Build your app
hyphae upload .

hyphae upload path-to-your-app

Support

Join our Discord for developer support!

Developer Notes

We're currently working on some major improvements to our SDK

Coming soon:

• Proper developer logs
• Integration with our VSCode extension to make the process of building, testing, and deploying apps CLI free

Happy building!