​
Build Your First App: WeatherChecker

In this tutorial we’ll build a simple WeatherChecker app. It has one tool that fetches the current weather for any city using the wttr.in API.

Prerequisites:

  • Python 3.10+
  • Virtual environment activated
  • Truffle SDK installed

​
1. Initialize

Open your terminal in your IDE of choice and run:

truffle init

You’ll be prompted for a name and description. This creates a project structure:

TruffleApp/
├── README.md           # Overview and guidance
└── src/
    ├── app/            # Your application code
    │   └── main.py     # Main app logic
    └── config/         # System & config files
        ├── manifest.json # App metadata
        ├── llm.xml       # Documentation to give to an LLM
        ├── icon.png      # App icon
        └── requirements.txt # Dependencies

​
2. Write your App

Open src/app/main.py and replace its contents with:

import truffle
import requests

@truffle.app(
    description="Checks the current weather for a specified city")
class WeatherChecker:
    def __init__(self):
        pass # Initialize any state if needed

    @truffle.tool(
        description="Get current weather for a specified city",
        icon="cloud.sun"
    )
    @truffle.args(
        city="Name of the city to fetch weather for"
    )
    def get_weather(self, city: str) -> str:
        """Fetches weather data from wttr.in and returns a simple text summary."""
        try:
            # self.client.tool_update(f"Fetching weather for {city}...") # Removed self.client usage
            print(f"Fetching weather for {city}...") # Placeholder for potential logging/feedback
            response = requests.get(f"http://wttr.in/{city}?format=3")
            response.raise_for_status() # Raise an exception for bad status codes
            return response.text
        except requests.exceptions.RequestException as e:
            # self.client.tool_update(f"Error fetching weather: {e}") # Removed self.client usage
            print(f"Error fetching weather: {e}") # Placeholder for potential logging/feedback
            raise ValueError(f"Failed to fetch weather for {city}: {e}")
        except Exception as e: # Catch other potential errors
            print(f"An unexpected error occurred: {e}")
            raise ValueError(f"An unexpected error occurred while fetching weather for {city}: {e}")


if __name__ == "__main__":
    truffle.run(WeatherChecker())

System Prompt (Optional)

You can define a system prompt for your app by adding a "system_prompt" key to the src/config/manifest.json file. This allows you to provide specific instructions or context to the LLM about how your app should behave. This field is not generated by truffle init but can be added manually.

​
3. Install Dependencies

Make sure requests is listed in src/config/requirements.txt:

requests>=2.28

Then install:

pip install -r src/config/requirements.txt

​
4. Build & Upload

Now package and upload your app:

truffle build
truffle upload
  • truffle build bundles your code into a deployable .truffle file.
  • truffle upload deploys it to your personal cloud instance, or your connected Truffle hardware.

​
5. Test Your App

Open the Truffle Client, select WeatherChecker, and ask:

What’s the weather in New York?

The Agent will invoke your get_weather("New York") tool and return something like:

New York: 🌤 80°F

You can extend this app with additional tools (e.g. forecasts, alerts) or customize icons and descriptions.