Agent Lagbaja

Name cannot be blank — Fri, 07 Nov 2025 13:47:47 +0000

Building Lagbaja: An AI-Powered Flashcard Generator

A production-ready A2A service that transforms PDFs into intelligent study flashcards

Overview

Lagbaja is an Agent-to-Agent (A2A) compliant backend service that converts PDF documents and text into study flashcards using Google's Gemini AI. It follows JSON-RPC 2.0 protocol, integrates with workflow platforms like Telex, and supports multiple input methods.

The Problem

Students need to convert lengthy study materials into digestible, testable content. Most flashcard tools require manual input and don't intelligently extract key concepts. Lagbaja solves this by:

Automatically generating flashcards from PDFs and text using AI
Following A2A protocol for seamless agent-to-agent communication
Supporting JSON-RPC 2.0 for standardized messaging

Architecture Overview

Lagbaja follows a clean, layered architecture built with Go 1.25.3:

HTTP Server → Handler Layer → Service Layer → External APIs
    ↓             ↓              ↓              ↓
  /a2a        A2AHandler    FlashcardSvc    Gemini AI
  /upload                   PDFService      PDF Parser
  /health

Key Components:

HTTP Server (main.go) - Routing, middleware, graceful shutdown
Handler Layer - JSON-RPC 2.0 and A2A message processing
Service Layer - Business logic for PDF processing and flashcard generation
Models - A2A, JSON-RPC, and domain structures

Key Features

Multiple Input Methods

Lagbaja accepts requests in three ways:

// Text Input
{"message": {"parts": [{"text": "Create flashcards about photosynthesis"}]}}

// PDF URL
{"message": {"parts": [{"text": "https://example.com/notes.pdf"}]}}

# File Upload
curl -X POST /upload -F "pdf=@notes.pdf"

Protocol Compliance

JSON-RPC 2.0: Standard error codes (-32700 to -32603), proper request/response format

A2A Protocol: Task management, structured artifacts, message history

{
  "result": {
    "status": {"state": "completed"},
    "artifacts": [{"name": "flashcardSet", "parts": [...]}],
    "history": [...]
  }
}

AI Generation

Uses Google Gemini (gemini-1.5-flash) to analyze content and generate 5-10 focused flashcards with questions, answers, and topic categorization.

Technical Decisions

Why Go?

Built-in concurrency with goroutines
Excellent HTTP and JSON standard library
Single binary deployment
Fast performance and low memory footprint

Why Gemini over Anthropic?

Primary reason: Anthropic API credit limitations. Gemini's generous free tier enabled continued development and production deployment.

Additional benefits: Simpler API, faster responses, native Google ecosystem integration.

Middleware Design

// Method enforcement + request logging
mux.Handle("/a2a", loggingMiddleware(methodGuard(handler, "POST")))

Clean separation of concerns keeps handlers focused on business logic.

Testing

Comprehensive test coverage with 11 suites and 23 test cases (100% pass rate):

HTTP method validation
JSON-RPC protocol compliance
Message parsing and validation
PDF processing and text extraction
Flashcard formatting and generation

go test ./... -v  # All tests passing

Telex Integration

Lagbaja integrates with Telex workflows via workflow.json:

{
  "category": "education",
  "nodes": [{
    "type": "a2a/mastra-a2a-node",
    "url": "http://lagbaja-production.up.railway.app/a2a",
    "parameters": {
      "model": "gemini-1.5-flash",
      "httpMethod": "POST"
    }
  }]
}

This enables workflow platforms to discover and communicate with Lagbaja automatically.

Deployment

Deployed on Railway with automatic builds:

GEMINI_API_KEY=<key>
PORT=8080

Includes graceful shutdown, health checks, and request timeouts for production reliability.

Usage Example

curl -X POST https://lagbaja-production.up.railway.app/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test",
    "method": "message/send",
    "params": {
      "message": {
        "parts": [{"kind": "text", "text": "Create flashcards about quantum mechanics"}]
      }
    }
  }'

Response: Structured flashcards with questions, answers, and topics in both text and JSON format.

Key Takeaways

Protocol Compliance: Following JSON-RPC 2.0 and A2A specs enables seamless integration
Testing: Comprehensive tests (23 cases) ensure reliability
Pragmatic Choices: Switched to Gemini due to Anthropic credit limits—practical constraints drive good decisions
Clean Architecture: Layered design with middleware keeps code maintainable

Future Enhancements

Batch PDF processing
Custom flashcard templates
Anki/Quizlet export formats
Caching for repeated requests
API authentication

Try It

Live: https://lagbaja-production.up.railway.app/a2a

Code: https://github.com/tobey0x/lagbaja

Quick Start:

git clone https://github.com/tobey0x/lagbaja
cd lagbaja
echo "GEMINI_API_KEY=your-key" > .env
go run main.go

Built with Go 1.25.3 • Google Gemini AI • Deployed on Railway

Zero Day at HNGi13

Name cannot be blank — Tue, 21 Oct 2025 10:59:11 +0000

Context and Goal

This task involved creating a simple API endpoint (/me) in any language and framework of choice so opted to using the Gin framework in Go. The critical requirement was that the API's response payload needed to include fresh data fetched from an external, third-party service Cat Fact

Why have I chosen Go? I'm currently learning Go and this serves as an opportunity to make it a project based learning.

The Core Lesson: Outgoing Traffic Control

The important architectural choice I faced was how to protect the third-party API from me. If my service goes viral(laughs) and gets 1,000 requests per second, I cannot afford to forward 1,000 requests to catfact.ninja. This would certainly cause me to be blocked.

Hence, I resorted to limiting outgoing traffic by implementing a Token Bucket using golang's rate package to strictly control the flow leaving my service (strict 0.5 requests per second).

If a request attempts to call the external API but the bucket is empty, we return a 429 Too Many Requests to the client, protecting the external service from my own overload.

Conclusion

It seems I've successfully built an API endpoint that is not only functional but is also resilient (with Timeouts), reliable (with UTC timestamps), and architecturally sound (with proper traffic control). Also, I hope I have not bitten more than I can chew by joining the rigorous HNG Internship while learning a new language.

DEV Community: Name cannot be blank