Hugging Face's logo

Spaces:
togitoon
/
tc-agent
Sleeping

App Files Community
tc-agent / docs /module-2 /README.md
togitoon's picture
togitoon
Initial
bf5f290
preview code
|
raw
history blame contribute delete
5.28 kB

Topcoder Challenge Steward Agent – Module 2 Architecture

This module describes the split architecture for the Topcoder Challenge Steward Agent, separating the user interface and backend agent logic.

1. User Interface (Frontend)

  • Framework: NestJS (API/backend) + Material UI (React-based UI)
  • Purpose:
    • Allow users to provide their challenge preferences (free text, tags, etc.)
    • Allow users to start/stop the agent for themselves
    • Simple, clean interface for managing notification settings
  • Key Features:
    • User authentication (optional, depending on deployment)
    • Form for entering/editing preferences
    • Button(s) to start/stop the agent
    • Status display (agent running, last run, etc.)
    • Communicates with the backend via REST API

2. Backend (Agent & API)

  • Framework: FastAPI (Python)
  • Purpose:
    • Store user preferences and email addresses in a database
    • Expose REST API endpoints for the frontend (CRUD for preferences, agent control)
    • Run the agent on a schedule (e.g., daily per user)
    • Poll the database for active agents and execute them
    • For each active agent:
      • Retrieve user preferences
      • Combine with system prompt
      • Run the agent logic (implemented in Python, with MCP integration)
      • Send notifications via Email MCP if suitable challenges are found
  • Key Features:
    • User management (basic, for mapping preferences to emails)
    • Preference storage (database: e.g., SQLite, PostgreSQL, etc.)
    • Scheduler (e.g., Celery, APScheduler, or FastAPI background tasks)
    • Integration with Topcoder MCP (fetch challenges, skills, etc.)
    • Integration with Email MCP (send notifications)

System Flow Diagram 

graph TD
  A[User] -- Preferences/Control --> B[Frontend (NestJS + Material UI)]
  B -- REST API --> C[Backend (FastAPI)]
  C -- Store/Retrieve --> D[(Database)]
  C -- Schedule/Run --> E[Agent Logic]
  E -- Fetch Challenges --> F[Topcoder MCP]
  E -- Send Email --> G[Email MCP]

Development Notes

  • The frontend and backend are decoupled and communicate via HTTP REST APIs.
  • The backend is responsible for all agent execution and persistence.
  • The agent logic is implemented in Python for easy integration with AI/ML libraries and MCP services.
  • The system is designed for extensibility (e.g., adding more notification channels, richer preference models).

Deploying to Hugging Face Spaces as a Single Docker Container

I can deploy this full-stack (NestJS + Material UI frontend, FastAPI backend) app as a single Docker container on Hugging Face Spaces. Below are the recommended steps and best practices:

1. Project Structure

  • I will place all code (frontend and backend) in the repository.
  • I will include a Dockerfile and README.md (with Hugging Face metadata).
  • I will add requirements.txt for Python dependencies and package.json/yarn.lock for Node dependencies if building the frontend in Docker.

2. Dockerfile Example (Multi-Stage Build) 

# Stage 1: Build frontend
FROM node:18 AS frontend-build
WORKDIR /app/frontend
COPY frontend/ .
RUN npm install && npm run build

# Stage 2: Build backend
FROM python:3.9 AS backend
RUN useradd -m -u 1000 user
WORKDIR /app

# Install Python dependencies
COPY --chown=user requirements.txt .
RUN pip install --no-cache-dir --upgrade -r requirements.txt

# Copy backend code
COPY --chown=user backend/ /app/backend

# Copy built frontend to backend's static directory
COPY --from=frontend-build /app/frontend/build /app/backend/static

# Set permissions
USER user
ENV HOME=/home/user PATH=/home/user/.local/bin:$PATH

# Expose the port expected by Hugging Face Spaces
EXPOSE 7860

# Start FastAPI (serving both API and static frontend)
CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]
  • I will adjust paths as needed for my project layout.
  • If I want to use Nginx or another server for static files, I will add a third stage.

3. Hugging Face README Metadata Block

I will add this YAML block at the top of my README.md:

---
title: Topcoder Challenge Steward Agent
emoji: 🏗️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---

4. Data Persistence

  • By default, data is not persisted between restarts.
  • For persistent storage, I will use the supabase free tier https://supabase.com/pricing directory or an external database.

5. Environment Variables & Secrets

  • I will set secrets and environment variables in the Hugging Face Space settings.
  • I will access them in my code via os.environ (Python) or process.env (Node.js).

6. Build & Push

  • I will push my code to my Hugging Face Space repository.
  • The Space will build and run my Dockerfile automatically.

References