Telex Weather Agent

Gamey001 — Wed, 05 Nov 2025 20:34:57 +0000

🌦️ Telex Weather Agent — FastAPI + Railway + Telex.im

🚀 Overview

This project is my Stage 3 Backend Task for HNG Internship.

I built an AI-powered Weather Agent that integrates with Telex.im — a platform for intelligent AI coworker agents.

The agent helps users fetch real-time weather data for any city in the world using FastAPI, deployed on Railway, and connected to Telex via the A2A protocol.

🧠 What the Agent Does

The Telex Weather Agent:

Accepts a city name as input from Telex conversations.
Fetches current weather data from the OpenWeather API.
Returns a concise and human-friendly weather summary.
Handles invalid or missing inputs gracefully.

Example Interaction

User: "What's the weather in Lagos?"

Agent: "The weather in Lagos is 30°C, clear sky, humidity 78%, and wind speed 3.2 m/s."

🧩 Tech Stack

Component	Technology
Language	Python
Framework	FastAPI
Hosting	Railway
API	OpenWeatherMap
Integration	Telex.im (A2A Protocol)

⚙️ Project Structure

Building a Dynamic Profile API with FastAPI

Gamey001 — Sun, 19 Oct 2025 19:59:01 +0000

🎯 Task Overview

In Stage 0 of hng13 backend, the goal was simple but powerful:

Build a RESTful API endpoint /me that returns your profile details along with a random cat fact fetched dynamically from an external API.

*This task tested our understanding of:
*
API design with proper JSON structure

Integrating external APIs

Handling network errors gracefully

Returning dynamic UTC timestamps

Deploying a small but complete backend app

🧩 Stack & Tools

Language: Python

Framework: FastAPI 🏎️

HTTP Client: Requests

Environment Management: python-dotenv

Deployment: Railway

Testing: cURL & browser

⚙️ Project Setup
🗂️ Structure

backend-wizards-stage0/
│
├── app/
│   ├── main.py
│   ├── config.py
│   └── utils/
│       └── cat_facts.py
├── requirements.txt
├── .env
├── Procfile
└── README.md

🧱 Main Endpoint

The /me endpoint returns:

{
  "status": "success",
  "user": {
    "email": "youremail@example.com",
    "name": "Your Full Name",
    "stack": "Python/FastAPI"
  },
  "timestamp": "2025-10-19T11:52:23.789Z",
  "fact": "Cats sleep for around 13 to 14 hours a day."
}

⚡ Core Logic (simplified)

@app.get("/me")
async def get_profile():
    timestamp = datetime.now(timezone.utc).isoformat()
    response = {
        "status": "success",
        "user": {
            "email": Config.USER_EMAIL,
            "name": Config.USER_NAME,
            "stack": Config.USER_STACK
        },
        "timestamp": timestamp,
        "fact": fetch_cat_fact()
    }
    return JSONResponse(content=response)

*Each request dynamically:
*
Fetches a new cat fact from Cat Facts API

Generates a fresh UTC timestamp

Returns all data in a consistent JSON schema

🧠 What I Learned
1️⃣ Working with External APIs

Using the requests library, I learned to:

Handle timeouts and connection errors

Extract specific JSON keys safely

Return fallback messages when the API fails

Example:

def fetch_cat_fact():
    try:
        res = requests.get("https://catfact.ninja/fact", timeout=5)
        res.raise_for_status()
        return res.json().get("fact")
    except requests.RequestException:
        return "Could not fetch cat fact at the moment."

*Error Handling Matters
*
Instead of letting the entire app crash when the Cat Facts API fails, the function gracefully returns a friendly message.
This makes the API robust and user-friendly — a key real-world backend skill.

3️⃣ Dynamic Data and Time Formatting

I learned how to generate ISO 8601 UTC timestamps:

datetime.now(timezone.utc).isoformat()

Every new request shows a fresh timestamp ⏰ — confirming the endpoint is truly dynamic.

4️⃣ Deployment & Environment Variables

This task reinforced best practices:

Keeping sensitive data (like name/email) in a .env file

Configuring environment variables in the hosting platform (Railway)

Using a Procfile to define the startup command

My Procfile:

web: uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}

Deployment on Railway was smooth:

Push code to GitHub

Connect repo on Railway

Add environment variables (USER_EMAIL, USER_NAME, USER_STACK)

Deploy 🚀

Visit https://yourappurl.up.railway.app/me

📸 Screenshots

(Add screenshots here of your running API on localhost and on Railway)

✅ Local run on http://127.0.0.1:8000/me

☁️ Live endpoint showing real-time cat facts

{
  "status": "success",
  "user": {
    "email": "jdoe@example.com",
    "name": "John Doe",
    "stack": "Python/FastAPI"
  },
  "timestamp": "2025-10-19T13:09:45.123Z",
  "fact": "Cats use their whiskers to detect objects and navigate tight spaces."
}

💡 Takeaways

A small API can teach big backend fundamentals — request handling, responses, error management, and clean JSON formatting.

Using FastAPI makes development extremely fast and intuitive with automatic docs at /docs.

I learned to appreciate clean error handling, environment separation, and deployment best practices.

🏁 Final Thoughts

This task reminded me that clarity + consistency = good backend design.
Even a simple endpoint like /me can demonstrate:

Professional structure

Error resilience

Proper documentation

You can check out the GitHub repository here:
👉 GitHub Repo

And the live API here:
👉 Live Endpoint

Author: Gamaliel Dashua

Stack: Python / FastAPI
Challenge: Hng13 - Backend Stage 0 🚀