ogonzalezc782/superpoderes-para-ia

Purpose

This repository packages an administrative AI agent for Colegio Universitario de Cartago (CUC). Users ask academic-data questions in natural language; the agent retrieves enrollment and grade data, performs multi-step analysis, and can send formatted email reports.

Primary Entry Point

The deployable artifact is the n8n workflow export: Agente IA Administrativo CUC.json. Import it into n8n, configure credentials, activate it, and access its chat trigger through n8n’s test or production chat URL.

Interaction and Orchestration

1. A user sends a chat message to the workflow.

2. The n8n AI Agent receives the message and conversational context.

3. Google Gemini interprets the request and selects one or more connected tools through function calling.

4. Tool results return to the agent, which synthesizes the final chat response or initiates an email action.

The orchestration, prompt, tool wiring, memory configuration, and trigger behavior are expected to reside in Agente IA Administrativo CUC.json.

Academic Data Boundary

Two workbook artifacts define the domain data model:

• Estudiantes.xlsx: enrollment records, centered on carnet, full name, and degree/career.

• Notas.xlsx: grade records, centered on full name, subject, and grade.

In deployment, these workbooks are hosted in Microsoft OneDrive or SharePoint and accessed through n8n Microsoft Excel nodes. The repository copies are sample/source data rather than a local runtime database.

Agent Tools and Actions

The workflow exposes three architecture-defining capabilities:

• Enrollment lookup against the student workbook: Estudiantes.xlsx.

• Grade lookup and performance analysis against the grades workbook: Notas.xlsx.

• Institutional email delivery via Gmail, including HTML-formatted reports.

Gemini decides whether to invoke one tool or combine them—for example, joining a student’s enrollment information with all grades before generating a response or email.

External Runtime and Services

n8n is the execution runtime, either n8n Cloud or self-hosted (Node.js 18+ is required only for self-hosted deployment). Material external dependencies are:

• Google Gemini API for chat reasoning and tool selection.

• Microsoft 365 Excel OAuth plus OneDrive/SharePoint for workbook access.

• Gmail API/OAuth for optional outbound messages.

Credential setup is intentionally environment-specific and should remain in n8n rather than repository files.

Operational Boundaries

The agent handles academic and personally identifiable student data, so production deployment needs authenticated chat access, least-privilege Microsoft/Gmail credentials, secret management, and log review. Service limits influence behavior: Gemini request quotas, Gmail daily sending limits, workbook format/size constraints, and a documented response-length limit.

Supporting Material

README.md is the setup and operational guide. Charla Superpoders para IA.pdf is presentation material and is not part of the runtime execution path.