DEV Community: Enol Casielles

Cómo Desarrollé MemoMate: Un Asistente Personal en Telegram con IA

Enol Casielles — Sun, 08 Dec 2024 10:25:03 +0000

Introducción

En este artículo quiero compartir mi experiencia desarrollando MemoMate, un asistente personal en Telegram que ayuda a gestionar y mejorar nuestras relaciones personales. La idea surgió de una necesidad personal: tener una forma sencilla de recordar detalles importantes sobre las personas que me importan - desde cumpleaños hasta conversaciones significativas.

¿Qué es MemoMate?

MemoMate es un bot de Telegram que actúa como un PRM (Personal Relationship Manager). A través de una conversación natural, puedes contarle información sobre tus contactos, y el bot se encarga de almacenar y organizar esta información de forma que puedas acceder a ella en el futuro. Vamos a ver aquí sus principales características.

Gestión de Contactos

Durante tu conversación con el bot, este irá detectando los contactos sobre los que estás hablando y los irá registrando en tu cuenta. Tendrá la capacidad de saber si el contacto ya existe en la base de datos y, en caso de que no, lo creará. También puedes pedirle que edite cualquier información sobre un contacto o incluso que lo elimine.

Información sobre Contactos

El bot está preparado para que le cuentes cualquier cosa que necesites recordar sobre cualquiera de tus contactos. El bot irá almacenando toda esta información para que más tarde puedas consultarla. Vamos a verlo con un ejemplo:

Imagina que tienes un amigo que se llama José y que el bot ya lo tiene registrado como un contacto tuyo. Podrías decirle algo como:

"Ayer estuve con mi amigo José y me comentó que se está planteando dejar su trabajo"

Ahora imagina que pasan 3 meses y vas a quedar con tu amigo José. Podrías ir a MemoMate y preguntarle:

"¿Qué me contó mi amigo José la última vez?"

El bot te responderá diciendo:

"José te dijo que se está planteando dejar su trabajo"

Recordatorios

Otra funcionalidad interesante del bot es la de los recordatorios. MemoMate te permite registrar recordatorios sobre cualquier contacto, para que te envíe un mensaje en la fecha asignada. Por ejemplo, podrías decirle:

"El próximo 15 de diciembre es el cumpleaños de mi amigo José. Recuérdame que le felicite"

El bot interpretará de este mensaje que tiene que crear un recordatorio para el próximo 15 de diciembre sobre el contacto José y para que le felicites. Cuando llegue dicha fecha, el bot te enviará un mensaje como:

"Recuerda felicitar a José por su cumpleaños"

Free vs Premium

MemoMate se podrá utilizar de forma gratuita, lo que permitirá un uso limitado de la cuenta. Cada usuario tendrá un número de mensajes que puede enviar al bot cada mes. Cuando agote estos mensajes, el usuario no podrá enviar más mensajes hasta que no se le renueven sus créditos o pase a Premium. Cuando se hace Premium, el usuario desbloquea la limitación de mensajes y puede hacer un uso ilimitado.

Plataforma Web

Además del bot en Telegram, MemoMate también cuenta con una plataforma web que otorga al usuario ciertas funcionalidades:

Gestión de la suscripción: A través de esta web el usuario podrá controlar la suscripción que convierte al usuario en Premium.
Gestión de Contactos: Además de la gestión de contactos que realiza el propio bot, el usuario contará con una sección en la web en la que también pueda realizar esta gestión y con una característica extra importante: importación vía csv.
Gestión de Eventos: Lo mismo para la información de los contactos. El usuario podrá ver y gestionar esta información también desde la aplicación web.
Analíticas: La aplicación web le dará al usuario algunos datos interesantes acerca del uso de su cuenta.
Landing Page Promocional: Esta Web también cuenta con la página explicativa del producto que serviría para promocionar y explicar el mismo al usuario.

Arquitectura y Tecnologías

MemoMate se compone de 2 componentes (o aplicaciones) principales:

Bot de Telegram: para manejar toda la interacción con los usuarios.
Aplicación Web: para que el usuario pueda gestionar su cuenta y los contactos.

Tecnologías empleadas

Vamos a ver aquí las tecnologías que he decidido emplear para implementar este producto y el porqué de cada una.

Monorepo con pnpm: Ambas aplicaciones (bot y web) tienen funcionalidad que es interesante compartir. Por esta razón, decidí utilizar una arquitectura de monorepo en el que vivan estas 2 aplicaciones y que cuente con paquetes que definan las funcionalidades que se deban compartir. PNPM fue la elección natural por su eficiencia en el manejo de dependencias y su excelente soporte para workspaces. Si quieres saber más sobre este tema te recomiento este artículo donde explico más en detalle.
PostgreSQL + Prisma: Necesitaba una base de datos robusta que pudiera manejar relaciones complejas entre usuarios, contactos y eventos. PostgreSQL fue el candidato perfecto. Prisma añade una capa que nos facilita tanto el manejo de las migraciones como la implementación de las diferentes comunicaciones con la base de datos que sean necesarias.
OpenAI: La API de OpenAI, especialmente con sus Assistants, ofrece capacidades avanzadas de procesamiento de lenguaje natural. La posibilidad de definir "tools" personalizadas que el asistente puede utilizar fue clave para implementar las funcionalidades principales del bot.
Next.js: Para la aplicación web, Next.js fue la elección ideal por varios motivos:
- Server Components para mejor rendimiento.
- App Router para la implementación de las diferentes secciones.
- API Routes para implementar los endpoints serverless que necesitemos.
Tailwind CSS y Shadcn: A la hora de definir la UI de la aplicación web, esta combinación es perfecta por la facilidad que otorga a la hora de crear los diferentes componentes de una forma robusta y eficiente.
Pinecone: Para implementar búsquedas semánticas sobre la información de los contactos, necesitábamos una base de datos vectorial. Pinecone destaca por su facilidad de uso, rendimiento y capacidad para manejar grandes volúmenes de datos vectoriales.
Telegraf: Para implementar el bot de telegram, optamos por utilizar la librería telegraf que destaca por su buen funcionamiento y facilidad de integración.

El Proceso de Desarrollo

Vamos a explicar ahora como se ha abordado el proceso de desarrollo del proyecto, pasando por todos los pasos que se han ido dando para llegar desde una idea inicial hasta un producto final. No vamos a entrar en detalle de absolutamente todas las piezas de código que se fueron desarrollando, ya que haríamos el artículo excesivamente extenso. Voy a ir explicando como se fueron definiendo las diferentes partes y parándome en aquellas que considero más interesantes. Recomiendo abrir el repositorio del proyecto y ver en más detalle la implementación realizada.

Definición del Proyecto

Este proceso comenzó definiendo claramente el alcance y la arquitectura. Apoyándome mucho en ChatGPT fuí refinando la idea y documentando como íbamos a realizar cada parte. El objetivo aquí era crear diferentes documentos que iba volcando en la carpeta docs. Esta fase de planificación fue crucial para tener una visión clara del camino a seguir y para poder disponer de la información necesaria para llevar a cabo un desarrollo eficiente con Cursor. En esta carpeta creamos diferentes documentos: explicación del proyecto, definición de la base de datos, arquitectura, etc. Esto nos permite que Cursor tenga conocimiento de lo que estamos desarrollando y nos ayude a iterar mucho más rápido.

Estructura Base

Se utilizó una arquitectura de monorepo con los diferentes componentes. Por un lado las 2 aplicaciones que ya mencionamos (el bot y la web) y por otro lado los diferentes paquetes en los que se apoyarán estas aplicaciones. También contamos con una aplicación extra que llamamos infra. Esta aplicación será básicamente un docker-compose que nos permite levantar la infra en local que necesitemos, en este caso únicamente la base de datos PostgreSQL.

A pesar de tener un único servicio en la infra, decidimos mantener un docker-compose para facilitar el agregar posibles servicios a futuro

En cuanto a los paquetes, tendremos los siguientes:

core: En donde implementaremos utilidades compartidas
database: Que se encargará de gestionar todo lo que tenga que ver con la base de datos usando Prisma. Modelos, migraciones, etc.
openai: Abstracción para la interacción con OpenAI. Definiremos en esta paquete clases y utilidades interesantes que nos facilitarán al creación y gestión del Asistente en OpenAI.

Sistema de Autenticación

El sistema de autenticación de la plataforma es algo inusual. La idea no es contar con un mecanismo de Login y Registro al uso, si no que sea el bot quien se encargue de gestionar esto. El bot tendrá la capacidad de identificar al usuario con el que está interactuando, creando usuarios nuevos en cada nueva conversación. Cuando el usuario tenga que ir a la plataforma web, tanto porque el bot se lo requiere o porque el usuario desea hacerlo, el bot será el responsable de generar un link único y temporal de acceso.

Para conseguir esto, se desarrolló un sistema de autenticación simple pero efectivo. El flujo funciona así:

Cuando el usuario necesita acceder a la web, el bot genera una sesión temporal con un token único. Ese link será válido solo durante 10 minutos (expiración de la sesión).

  private async createSessionUrl(userId: string) {
    const session = await prisma.session.create({
      data: {
        userId: userId,
        expiresAt: new Date(Date.now() + 1000 * 60 * 10),
      }
    });
    const link = `${process.env.FRONTEND_URL}/login?token=${session.id}`;
    return link;
  }

El bot envía este link al usuario para que pueda hacer clic en el, lo cual disparará la Api Route /login en la web. Esta ruta hará lo siguiente:
- Verificar que el token sea válido y no haya expirado
- Si es válido, crea una cookie de 30 días y redirige a /dashboard
- Si no es válido, redirige a una página de error

export async function LoginRoute(request: Request) {
  const { searchParams } = new URL(request.url);
  const token = searchParams.get("token");
  let errorType = null;
  try {
    if (!token) {
      throw new CustomError({
        message: "Token no proporcionado",
        type: "INVALID_TOKEN",
        statusCode: 400,
      });
    }
    const session = await prisma.session.findFirst({
      where: {
        id: token,
        expiresAt: {
          gt: new Date(),
        },
      },
      include: {
        user: true,
      },
    });

    if (!session) {
      throw new CustomError({
        message: "Sesión inválida o expirada",
        statusCode: 401,
        type: "INVALID_TOKEN",
      });
    }

    // Crear cookie con el ID del usuario
    cookies().set("userId", session.userId, {
      httpOnly: true,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax",
      path: "/",
      maxAge: 60 * 60 * 24 * 30, // 30 días
    });

    // Retornamos una redirección
    return NextResponse.redirect(new URL("/dashboard", request.url));
  } catch (error) {
    console.error(error);
    if (error instanceof CustomError) errorType = error.type;
    else errorType = "INTERNAL_SERVER_ERROR";
  }
  redirect(`/error?type=${errorType}`);
}

De esta forma, conseguimos un mecanismo sencillo pero seguro y efectivo para que el usuario pueda acceder a su cuenta en la web desde Telegram. El usuario una vez identificado, ya podrá volver a su cuenta siempre que quiera (durante 30 días) simplemente accediendo a la web. Cuando la cookie caduque, deberá volver al bot para generar un nuevo link de acceso.

Integración con OpenAI

Para manejar la interacción con OpenAI de forma limpia y reutilizable, se creó un paquete dedicado @memomate/openai que abstrae toda la complejidad de la API. Este paquete implementa cuatro clases principales:

Agent

La clase Agent representa un asistente de OpenAI y maneja su ciclo de vida. Para poder utilizar los Asistentes de OpenAI lo primero que necesitas es crear uno, que lo puedes hacer usando su API o directamente a través de su plataforma. En nuestro caso, creamos el asistente directamente en la plataforma y metimos su id como una variable de entorno para poder recuperarlo a través de la API, dentro de esta clase Agent

El asistente es la entidad en OpenAI a la que se le especifica su propósito y como debe operar. También se le especifica el modelo que debe utilizar, así como las herramientas que tiene disponibles para extender funcionalidad.

interface Props {
  id: string;
  name: string;
  description: string;
  instructions: string;
  model?: string;
  tools: Array<Tool>;
}

export class Agent {
  // ...
  async init() {
    let openAiAssistant = await openaiClient.beta.assistants.retrieve(this.id);
    const shouldUpdate = this.shouldUpdate(openAiAssistant);
    if (shouldUpdate) {
      openAiAssistant = await openaiClient.beta.assistants.update(
        this.id,
        this.generateBody()
      );
    }
    this.assistant = openAiAssistant;
  }
}

Esta clase Agent también cuenta con una funcionalidad para comprobar si el asistente debe ser actualizado en OpenAI o no. La idea es que podamos desde el propio código del proyecto especificar como debe comportarse el asistente. El método shouldUpdate, compara los parámetros del Asistente en OpenAI con lo que hemos especificado en local (modelo, instrucciones, tools empleadas, etc.) Si detecta diferencias, actualizará el asistente en OpenAI, garantizando que desde el propio código controlemos su comportamiento.

  private shouldUpdate(openAiAssistant: Assistant): boolean {
    if (this.name !== openAiAssistant.name) return true;
    if (this.description !== openAiAssistant.description) return true;
    if (this.instructions !== openAiAssistant.instructions) return true;
    if (this.model !== openAiAssistant.model) return true;
    if (this.tools.length !== openAiAssistant.tools.length) return true;
    return false;
  }

Tool

Los asistentes están capacitados para ejecutar herramientas o tools, que son piezas de código que nos permiten llevar a cabo acciones que el propio Asistente no puede realizar por sí mismo. Por ejemplo, en nuestro caso, necesitaremos una Tool que cree un nuevo contacto. Para conseguir esto, lo que se hace es, primero especificarle al asistente que cuenta con una tool para crear un contacto y como la debe utilizar. Y, por otro lado, crear la propia tool para implementar dicha creación de usuario.

Para dar soporte a esto, la case abstracta Tool define la estructura para las herramientas que puede usar el asistente:

export abstract class Tool {
  name: string;
  description: string;
  parameters: any;

  constructor({ name, description, parameters }: ToolParams) {
    this.name = name;
    this.description = description;
    this.parameters = parameters;
  }

  abstract run(parameters: RunProps): Promise<string>;
}

Cada Tool que necesitemos crear y agregar al Agente, tendrá que ser una extensión de esta clase y deberá implementar el método run para realizar su función.

Thread

El siguiente concepto para comunicarnos con los asistentes de OpenAI es el Thread o hilo comunicación, que básicamente es cada conversación que tenga el Asistente. La idea en MemoMate es que cada usuario tenga su Thread propio, que se creará a la vez que la creación del usuario y permitirá mantener su propia conversación.

La clase Thread que implementamos en este paquete @memomate/openai se encarga de implementar toda esta funcionalidad. Básicamente nos permite lo siguiente:

Crear un nuevo hilo. Lo usaremos cuando se cree un nuevo usuario.

  static async create() {
    const thread = await openaiClient.beta.threads.create();
    return thread.id;
  }

Enviar un mensaje a un hilo. Se disparará con cada nuevo mensaje del usuario, a su hilo correspondiente.

  async send(message: string, retries: number = 1): Promise<string> {
    if (!this.agent) throw new Error("Assistant not set");
    if (!this.thread) await this.init();
    await openaiClient.beta.threads.messages.create(this.id, {
      role: "user",
      content: message,
    });
    this.run = await openaiClient.beta.threads.runs.create(this.id, {
      assistant_id: this.agent.id,
    });
    while (true) {
      await this.waitUntilDone();
      if (this.run.status === "completed") {
        const _message = await this.extractMessage();
        return _message;
      } else if (this.run.status === "requires_action") {
        await this.processAction();
      } else {
        const err = "Run failed: " + this.run.status;
        console.log(err);
        if (retries < MAX_RETRIES) {
          console.log("Retrying in 30s...");
          await new Promise((resolve) => setTimeout(resolve, 30000));
          return this.send(message, retries + 1);
        }
        const _message = this.generateFailedMessage();
        return _message;
      }
    }
  }

Dentro de este método send, se procesa la respuesta que nos da OpenAI, que puede ser un mensaje a devolver o una herramienta a ejecutar. Cuando sea una herramienta a ejecutar, buscaremos la herramienta correspondiente dentro de las tools del Agente y ejecutaremos su método run, devolviendo al asistente el resultado de dicha ejecución para que pueda continuar y entregar al usuario una respuesta final.

  private async processAction() {
    const toolsToExecute =
      await this.run.required_action.submit_tool_outputs.tool_calls;
    const toolsResults = [];
    for (const toolToExecute of toolsToExecute) {
      const toolName = toolToExecute.function.name;
      const tool = this.agent.tools.find((t) => t.name === toolName);
      const toolResult = tool
        ? await tool.run({
            ...JSON.parse(toolToExecute.function.arguments),
            metadata: this.metadata,
          })
        : "ERROR: no existe ninguna herramienta con el nombre que has indicado. Inténtalo de nuevo con el nombre correcto. La lista de herramientas disponibles es la siguiente: " +
          this.agent.tools.map((t) => t.name).join(", ");
      toolsResults.push({
        tool_call_id: toolToExecute.id,
        output: toolResult.toString(),
      });
    }
    this.run = await openaiClient.beta.threads.runs.submitToolOutputs(
      this.id,
      this.run.id,
      {
        tool_outputs: toolsResults,
      },
    );
  }

Embeddings

Otro concepto que necesitamos de OpenAI es el de los embeddings, que es la transformación de cierto texto en un formato vectorial que nos permita realizar búsquedas semánticas. Esto lo usaremos para poder recuperar los contactos del usuario. Cada vez que se cree o se actualice un contacto, generaremos su embedding correspondiente y lo guardaremos en Pinecone, para poder buscarlo en el futuro.

Para maneja esta generación de embeddings hemos creado esta clase Embeddings

export class Embeddings {
  private model = 'text-embedding-3-small';
  private dimensions = 1024;

  async generateEmbedding(text: string): Promise<number[]> {
    const response = await openaiClient.embeddings.create({
      model: this.model,
      dimensions: this.dimensions,
      input: text,
      encoding_format: 'float'
    });

    return response.data[0].embedding;
  }
}

De esta forma, el paquete @memomate/openai nos proporciona una capa de abstracción sobre la API de OpenAI, facilitando su uso y permitiendo una mayor flexibilidad en futuras implementaciones.

Implementación del Asistente

Una vez contamos con este paquete @memomate/openai ya estamos en disposición de proceder con la implementación del Asistente. En la aplicación bot, creamos una nueva carpeta assistant que se encargue de esto.

Empezamos con las tools, o las herramientas que le daremos al asistente para que pueda realizar las diferentes acciones necesarias: Crear un Contacto, Buscar un Contacto, Crear un Evento, etc. Cada herramienta será una clase que extienda de la clase abstracta Tool. El método run será el que se ejecuta cuando el asistente detecte que debe usar esta Tool. Y por tanto, en este método run es donde definimos lo que queremos que esta Tool realice.

export class CreateContactTool extends Tool {
  constructor() {
    super({
      name: "CreateContact",
      description:
        "Esta herramienta crea un nuevo contacto en la base de datos.",
      parameters: {
        type: "object",
        properties: {
          name: {
            type: "string",
            description:
              "El nombre del contacto que se desea crear.",
          },
          relation: {
            type: "string",
            description:
              "La relación del contacto con el usuario. Ejemplo: 'Amigo', 'Familiar', 'Trabajo', etc.",
          },
          location: {
            type: "string",
            description:
              "La ubicación del contacto. Puede ser una ciudad, un país, etc. Ejemplos: 'Madrid', 'Asturias', 'Argentina', etc.",
          },
        },
        required: ["name"],
      },
    });
  }

  async run(parameters: CreateContactRunProps): Promise<string> {
    try {
      console.log("Creando contacto...");
      const { metadata, name, relation, location } = parameters;

      // Crear el contacto en la base de datos
      const contact = await prisma.contact.create({
        data: {
          name,
          relation,
          location,
          userId: metadata.userId
        }
      });

      // Generar el texto para el embedding
      const contactText = `Nombre: ${name}${relation ? `, Relación: ${relation}` : ''}${location ? `, Ubicación: ${location}` : ''}`;

      // Generar embedding usando OpenAI
      const embeddings = new Embeddings();
      const embeddingValue = await embeddings.generateEmbedding(contactText);

      // Indexar en Pinecone
      await PineconeService.getInstance().upsertContact(
        metadata.userId,
        contact.id,
        embeddingValue
      );

      return `He creado el contacto ${name} correctamente. Su ID es ${contact.id}.`;
    } catch (e) {
      console.error(e);
      return `No se ha podido crear el contacto.`;
    }
  }
}

A continuación, creamos los archivos de texto instructions.md y description.md (formato markdown), para definir la descripción y las instrucciones de nuestro asistente. Aquí es donde le explicamos a nuestro asistente como debe actuar para llevar a cabo su propósito.

Y ya por último, creamos la clase MemoMateAssistant, que será la que se encargue de crear e inicializar el agente juntando todas las anteriores piezas y de exponer un método sendMessage que permita enviarle un nuevo mensaje a este Agente usando el hilo del usuario en cuestión.

export class MemoMateAssistant {
  private agent: Agent;
  private static instance: MemoMateAssistant;

  private constructor() {
    this.agent = new Agent({
      id: process.env.OPENAI_ASSISTANT_ID,
      name: "MemoMate Assistant",
      description: path.join(__dirname, "description.md"),
      instructions: path.join(__dirname, "instructions.md"),
      model: "gpt-4o-mini",
      tools: [
        new CreateContactTool(),
        new UpdateContactTool(),
        new DeleteContactTool(),
        new SearchContactTool(),
        new CreateEventTool(),
        new GetCurrentDateTool(),
        new CreateReminderTool(),
        new GetContactEventsTool(),
      ],
    });;
  }

  static getInstance(): MemoMateAssistant {
    if (!MemoMateAssistant.instance) {
      MemoMateAssistant.instance = new MemoMateAssistant();
    }
    return MemoMateAssistant.instance;
  }

  async init() {
    try {
      await this.agent.init();
      console.log("Asistente inicializado correctamente");
    } catch (error) {
      console.error("Error al inicializar el asistente:", error);
      throw error;
    }
  }

  async sendMessage(userId: string,threadId: string, message: string): Promise<string> {
    try {
      const thread = new Thread<ThreadMetadata>({
        id: threadId,
        agent: this.agent,
        metadata: {
          userId: userId,
        },
      });
      await thread.init();
      const response = await thread.send(message);
      return response;
    } catch (error) {
      if (error instanceof Error) {
        return error.message;
      }
      return "Error al enviar mensaje";
    }
  }
}

Una cosa a destacar es la inicialización del agente. Como podemos ver, y en línea con lo que comentábamos en el punto anterior, el Asistente ya lo tenemos creado y contamos con su id en OpenAI, el cual mantenemos en una variable de entorno para que directamente se recupere y, si es necesario, se actualice.

Conectar Bot con Asistente. Clase MemoMateProcessor

Una vez tenemos el asistente ya configurado, el siguiente paso es conectarlo al bot de Telegram para que el usuario pueda interactuar con él. Aquí es donde entra en juego la clase MemoMateProcessor. Esta clase se encarga de definir métodos para ser ejecutados en diferentes eventos que el bot de Telegram nos emita, como cuando el usuario inicia una nueva conversación, o cuando envía un mensaje. Para cada una de estas acciones, creamos un método en esta clase que lo gestione. Por ejemplo, cuando el usuario dispare el comando /help, haremos que se ejecute el método handleHelp de esta clase:

  public async handleHelp(ctx: Context) {
    const message = helpTemplate();
    ctx.reply(message, {
      parse_mode: 'HTML'
    });
  }

Este método simplemente define un html con el mensaje que le queremos dar al usuario, en este caso con la ayuda de como usar el bot. A través de objeto Context, respondemos al usuario enviando dicho mensaje en formato html.

El método más interesante en esta clase es el handleMessage, que será el que se ejecute con cada nuevo mensaje del usuario. Vamos a ver un poco lo que se hace aquí.

  public async handleMessage(ctx: TextMessageContext) {
    try {
      const telegramUserId = ctx.message.from.id;
      const chatId = ctx.message.chat.id;
      const message = ctx.message.text;

      const user = await this._getOrCreateUser(telegramUserId, chatId);

      const canSend = user.stripeSubscriptionId || user.credits > 0;

      if (!canSend) {
        const link = await this.createSessionUrl(user.id);
        ctx.reply(limitMessageTemplate(link), {
          parse_mode: 'HTML'
        });
        return;
      }

      await prisma.messageLog.create({
        data: {
          userId: user.id,
          message: message,
          direction: MessageLogDirection.INCOMING,
        }
      });

      const response = await this.assistant.sendMessage(user.id, user.openaiThreadId, message);

      await prisma.messageLog.create({
        data: {
          userId: user.id,
          message: response,
          direction: MessageLogDirection.OUTGOING,
        }
      });

      if (!user.stripeSubscriptionId) {
        await prisma.user.update({
          where: { id: user.id },
          data: {
            credits: { decrement: 1 }
          }
        });
      }

      ctx.reply(response);
    } catch (error) {
      console.error(error);
    }
  }

En primer lugar, recuperamos a través del Context los datos que necesitamos para poder identificiar al usuario y el mensaje que nos envía. Llamamos a un método privado _getOrCreateUser que se encarga de recuperar este usuario en nuestra base de datos, o de crearlo si no existiera.

Es interesante ver la implementación de este método _getOrCreateUser. Al crear el usuario también creamos el Thread que nos permite abrir una nueva conversación con el asistente. De esta forma ya tendremos todo listo para que este nuevo usuario pueda enviar mensajes al asistente.

El siguiente paso es analizar si el usuario puede enviar mensajes al asistente o no. Muy sencillo, podrá enviar si es Premium o, en su defecto, si el número de créditos es mayor que 0. Si no puede enviar, resolvemos este método enviando un mensaje estándar que le sugiera al usuario ir a la plataforma Web para hacerse Premium.

En caso contrario, ya solo nos queda enviar el mensaje del usuario al asistente, a través del sendMessage del MemoMateAssistant. Si el usuario no es Premium, le restamos crédito. Guardamos ambos mensajes (el del usuario y la respuesta) en un Log de mensajes. Y, finalmente, respondemos al usuario con la respuesta del asistente.

Crons para recordatorios

Para manejar tanto los recordatorios como la renovación de créditos de usuarios gratuitos, implementamos un sistema de tareas programadas usando la librería cron. Se creó una clase CronManager que gestiona dos trabajos principales:

Procesamiento de Recordatorios: Se ejecuta cada minuto para verificar si hay recordatorios pendientes que deban ser enviados a los usuarios. Cuando encuentra recordatorios cuya fecha de notificación ha llegado, envía un mensaje por Telegram al usuario correspondiente.

El parámetro telegramChatId que guardamos en el usuario cuando lo creamos es lo que necesitamos para poder enviar un mensaje a ese usuario en Telegram

async processReminders() {
  const pendingReminders = await prisma.reminder.findMany({
    where: {
      completed: false,
      remindAt: {
        lte: new Date()
      }
    },
    include: {
      user: true,
      contact: true
    }
  });

  for (const reminder of pendingReminders) {
    let message = `🔔 Recordatorio: ${reminder.message}`;
    if (reminder.contact) {
      message += `\nContacto: ${reminder.contact.name}`;
    }

    await this.bot.telegram.sendMessage(
      reminder.user.telegramChatId.toString(),
      message
    );

    await prisma.reminder.update({
      where: { id: reminder.id },
      data: { completed: true }
    });
  }
}

Renovación de Créditos: Se ejecuta diariamente a las 3 AM para renovar los créditos de los usuarios gratuitos. Busca usuarios cuya fecha de renovación haya llegado y les asigna nuevamente su cuota mensual de créditos:

async renewCredits(): Promise<void> {
  const usersToRenew = await prisma.user.findMany({
    where: {
      stripeSubscriptionId: null,
      renewAt: {
        lt: new Date()
      }
    }
  });

  for (const user of usersToRenew) {
    await prisma.user.update({
      where: { id: user.id },
      data: {
        credits: DEFAULT_CREDITS,
        renewAt: addMonths(new Date(), 1)
      }
    });
  }
}

La implementación actual es simple pero efectiva, aunque tiene margen de mejora. Por ejemplo, el procesamiento tanto de recordatorios como de renovación de créditos se realiza de forma secuencial, lo que podría ser un problema si el número de usuarios crece significativamente. Una mejora futura sería implementar un sistema de procesamiento por lotes para manejar grandes volúmenes de datos de manera más eficiente.

Pinecone para la búsqueda de contactos

Uno de los desafíos más interesantes fue implementar un sistema que permitiera al asistente identificar correctamente de qué contacto está hablando el usuario, incluso cuando la referencia no es exacta. Por ejemplo, si el usuario dice "mi amigo Juan de Madrid", el sistema debe ser capaz de encontrar el contacto correcto aunque esté guardado como "Juan García".

Para lograr esto, implementamos búsqueda semántica utilizando Pinecone, una base de datos vectorial que nos permite buscar similitud entre textos. El proceso funciona así:

Indexación de Contactos: Cuando se crea o actualiza un contacto, generamos un embedding (una representación vectorial del texto) que incluye toda la información relevante del contacto:

      // Dentro de CreateContactTool

      // Generar el texto para el embedding
      const contactText = `Nombre: ${name}${relation ? `, Relación: ${relation}` : ''}${location ? `, Ubicación: ${location}` : ''}`;

      // Generar embedding usando OpenAI
      const embeddings = new Embeddings();
      const embeddingValue = await embeddings.generateEmbedding(contactText);

      // Indexar en Pinecone
      await PineconeService.getInstance().upsertContact(
        metadata.userId,
        contact.id,
        embeddingValue
      );

Búsqueda de Contactos: Cuando el asistente necesita identificar un contacto, utiliza la herramienta SearchContactTool que convierte la consulta en un embedding y busca coincidencias en Pinecone:

async run(parameters: SearchContactRunProps): Promise<string> {
  const searchText = `Nombre: ${name}${relation ? `, Relación: ${relation}` : ''}${location ? `, Ubicación: ${location}` : ''}`;

  const embeddings = new Embeddings();
  const queryEmbedding = await embeddings.generateEmbedding(searchText);

  const results = await PineconeService.getInstance().searchSimilarContacts(
    metadata.userId,
    queryEmbedding,
    1 // Solo necesitamos el más similar
  );

  if (results.length > 0 && results[0].score && results[0].score > 0.7) {
    return `Contacto encontrado con ID: ${results[0].id}`;
  }
  return "No se encontró ningún contacto que coincida...";
}

La implementación se centraliza en la clase PineconeService, que maneja toda la interacción con Pinecone:

export class PineconeService {
  private indexName = 'memomate-contacts';
  private dimension = 1024;

  async init() {
    try {
      const pinecone = getPineconeClient();

      // Verificar si el índice existe
      const existingIndexes = await pinecone.listIndexes();

      const indexExists = existingIndexes?.indexes?.some(
        (index: IndexModel) => index.name === this.indexName
      );

      if (!indexExists) {
        // Crear el índice si no existe
        await pinecone.createIndex({
          name: this.indexName,
          dimension: this.dimension,
          metric: 'cosine',
          spec: {
            serverless: {
              cloud: 'aws',
              region: 'us-east-1'
            }
          },
        });

        console.log('Índice de Pinecone creado correctamente');
      }
    } catch (error) {
      console.error('Error al inicializar Pinecone:', error);
      throw error;
    }
  }

  async searchSimilarContacts(userId: string, queryEmbedding: number[], limit: number = 5) {
    try {
      const pinecone = getPineconeClient();
      const index = pinecone.index(this.indexName);

      const results = await index.query({
        vector: queryEmbedding,
        filter: {
          userId: userId
        },
        topK: limit,
        includeMetadata: true
      });

      return results.matches;
    } catch (error) {
      console.error('Error al buscar contactos similares:', error);
      return [];
    }
  }
}

Esta implementación nos permite una búsqueda "fuzzy" de contactos que va más allá de la coincidencia exacta de texto. El sistema entiende el contexto y las relaciones semánticas, permitiendo que el asistente identifique correctamente los contactos incluso cuando el usuario los menciona de forma informal o incompleta.

Web en Next

Hasta aquí hemos visto todo lo que tiene que ver con el bot o la integración con OpenAI. Vamos a ver ahora muy brevemente la implementación que hemos hecho en el lado de la Web.

La aplicación Web de MemoMate se implementó utilizando Next.js 14, aprovechando sus Server Components y con el App Router. Se trata de una implementación relativamente sencilla que sirve como complemento al bot de Telegram, permitiendo a los usuarios gestionar su cuenta y visualizar sus datos de una forma más estructurada.

La web consta de las siguientes secciones principales:

Landing Page: Una página de inicio atractiva que presenta el producto, sus características principales y ejemplos de uso. Implementada con componentes interactivos y un diseño moderno usando Tailwind. Anima al usuario a acceder al bot y, cuando detecta que el usuario está autenticado, le muestra un enlace para acceder a su dashboard.
Dashboard: Muestra un resumen de la actividad del usuario, incluyendo estadísticas sobre sus contactos y uso del bot
Contactos: Permite ver, editar y eliminar contactos, así como importar contactos mediante CSV
Eventos: Visualización y gestión de los eventos registrados para cada contacto
Suscripción: Panel para gestionar la suscripción Premium mediante Stripe

Lo más interesante de la implementación web es su mecanismo de autenticación, que ya explicamos anteriormente. En lugar de un sistema tradicional de login/registro, la autenticación se realiza a través del bot de Telegram, que genera links temporales de acceso. Este enfoque no solo simplifica la experiencia del usuario sino que también refuerza la integración entre el bot y la web.

La UI se construyó utilizando Tailwind CSS junto con los componentes de Shadcn/ui, lo que nos permitió crear una interfaz moderna y responsive de forma rápida y mantenible.

Al ser una implementación bastante estándar de Next.js, no profundizaremos más en los detalles técnicos. El código fuente está disponible en el repositorio para aquellos interesados en explorar la implementación completa.

Suscripciones con Stripe

La gestión de suscripciones es una parte fundamental de MemoMate, ya que determina el acceso a las funcionalidades Premium. Implementamos un sistema de suscripciones usando Stripe, que es gestionado desde la plataforma Web y que se reflejan en la base de datos para que el bot pueda saber si un usuario es Premium o no y actuar en consecuencia.

Interfaz de Suscripción

La página de suscripción proporciona una interfaz clara para que los usuarios gestionen su plan. Controlará si el usuario tiene una suscripción activa o no, mostrándole la UI correspondiente. En cualquier caso, podrá gestionar su suscripción, tanto para activarla como para cancelarla, siempre redireccionando al checkout de Stripe.

Integración con el Bot

El bot, en el MemoMateProcessor, verifica el estado de la suscripción antes de procesar cada mensaje:

public async handleMessage(ctx: TextMessageContext) {

  // 

  const user = await this._getOrCreateUser(telegramUserId, chatId);

  // Verificar si el usuario puede enviar mensajes
  const canSend = user.stripeSubscriptionId || user.credits > 0;

  if (!canSend) {
    const link = await this.createSessionUrl(user.id);
    ctx.reply(limitMessageTemplate(link), {
      parse_mode: 'HTML'
    });
    return;
  }

  // Procesar el mensaje...
}

Webhooks de Stripe

Para mantener sincronizado el estado de la suscripción, implementamos un webhook que procesa los eventos de Stripe. Esta es la forma que tenemos de enterarnos si el usuario decida cancelar la suscripción y, en consecuencia, debemos eliminar el Premium en el usuario. Desde ese momento le asignamos los créditos iniciales y le marcamos la fecha de renovación dentro de un mes.

export default async function StripeWebhookRoute(req: Request) {
  try {
    const body = await req.text();
    const signature = req.headers.get("stripe-signature")!;
    const event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    if (event.type === "customer.subscription.deleted" || 
        event.type === "customer.subscription.updated") {
      const subscription = event.data.object as Stripe.Subscription;

      if (subscription.status !== "active") {
        await prisma.user.updateMany({
          where: {
            stripeSubscriptionId: subscription.id as string,
          },
          data: {
            stripeSubscriptionId: null,
            renewAt: addMonths(new Date(), 1),
            credits: DEFAULT_CREDITS,
          },
        });
      }
    }

    return NextResponse.json({ received: true });
  } catch (error) {
    console.error(error);
    if (error instanceof CustomError) return apiError(error);
    return apiError(
      new CustomError({
        message: "Error interno del servidor",
        statusCode: 500,
      }),
    );
  }
}

En resumen, este sistema nos permite:

Gestión Transparente: Los usuarios pueden gestionar su suscripción fácilmente desde la web
Actualización Automática: El estado de la suscripción se actualiza automáticamente en la base de datos cuando ocurren eventos en Stripe
Control de Acceso: El bot verifica el estado de la suscripción antes de procesar cada mensaje
Degradación Graciosa: Cuando un usuario cancela su suscripción, vuelve automáticamente al plan gratuito con sus créditos mensuales

Mejoras Futuras y Conclusión

Durante el desarrollo de MemoMate, han surgido varias ideas para mejoras futuras que podrían enriquecer aún más la experiencia:

Procesamiento en Lotes: Implementar un sistema de procesamiento por lotes para manejar recordatorios y renovaciones de créditos de forma más eficiente.
Integración con Más Plataformas: Expandir más allá de Telegram, añadiendo soporte para WhatsApp o Discord.
Mejoras en la Búsqueda: Refinar el sistema de búsqueda semántica para obtener resultados aún más precisos.

También es importante destacar que el proyecto es puramente educativo. Por eso no hemos mencionado nada acerca de despliegues o puesta en producción. Si alguien ve interesante este proyecto y quiere llevar a cabo las acciones necesarias para poner en marcha este producto en el mercado, que no dude en contactarme 😉

El desarrollo de MemoMate ha sido un viaje fascinante que me ha permitido explorar y combinar diferentes tecnologías modernas. Desde la integración con OpenAI hasta la implementación de búsquedas semánticas con Pinecone, cada parte del proyecto ha presentado sus propios desafíos y aprendizajes.

Si te ha interesado este proyecto y quieres saber más, puedes encontrarme en:

También dejo por aquí de nuevo el código completo en GitHub para que lo puedas explorar y probar.

¡Espero que este artículo te haya resultado útil e interesante! Si tienes cualquier duda, sugerencia o simplemente quieres compartir tu experiencia, estaré encantado de escucharte. 🚀

Cómo uso Cursor para ser más productivo en desarrollo web

Enol Casielles — Sat, 23 Nov 2024 19:30:25 +0000

En este artículo, quiero compartir cómo estoy usando Cursor para mejorar mi productividad en el desarrollo web. Explicaré desde cómo organizo la documentación del proyecto hasta las técnicas que uso para obtener el máximo beneficio en cada iteración de desarrollo. Vamos a desglosarlo en varias secciones.

La importancia de una buena documentación

Mantener una buena documentación es esencial para que cualquier proyecto se mantenga organizado y pueda ser escalable a largo plazo. En cada repositorio que gestiono, tengo una carpeta llamada docs en la raíz del proyecto. Aquí es donde centralizo toda la información y organizo los archivos de documentación de manera que puedan ser fácilmente referenciados cuando trabajo con Cursor. Algunos de los archivos mínimos que suelo incluir son:

project.md: Aquí describo el proyecto sin entrar en cuestiones técnicas, proporcionando un contexto general.
arquitecture.md: Documento que explica en profundidad la arquitectura del proyecto.
database.md: Archivo donde detallo el modelo de datos y cualquier aspecto relacionado con la base de datos.

Además, si el proyecto tiene varias partes (por ejemplo, una API y una aplicación web), creo archivos adicionales específicos para cada una. Por ejemplo:

api.md y web.md: En cada uno describo los requisitos, las tecnologías a utilizar y cómo organizaremos el código en cada parte.

Mantener esta estructura bien definida es clave poder darle a Cursor toda la información contextual que pueda necesitar.

Creación de la documentación con ChatGPT

Para crear esta documentación, suelo apoyarme en ChatGPT. Abro una nueva conversación con un prompt similar al siguiente:

Eres un experto en el análisis y planificación de proyectos de software. Tengo una idea en mente que quiero desarrollar. Quiero que me acompañes en todo el proceso, que trabajemos en conjunto en esta idea. **No contestes con respuestas muy largas y genéricas a no ser que te lo pida explícitamente** Quiero que analicemos la idea en conjunto, viendo la mejor forma de abordarla. Puedes y debes poner en duda cualquier cosa que se te ocurra para que ambos le busquemos soluciones. ¿Empezamos?

Un prompt como este ayuda mucho a que el asistente te acompañe en todo el viaje y que conjuntamente lleguemos a una definición del proyecto bastante rigurosa. A partir de aquí ya empiezo a explicarle el proyecto y, a continuación, procedemos a definir cada una de las partes. El objetivo de esta conversación es construir el conjunto de ficheros necesarios que expliquen el proyecto a desarrollar de forma rigurosa. Toda esta documentación la voy volcando en una carpeta docs\ en la raíz de mi proyecto.

Partir de un proyecto base

Para mantener un flujo de trabajo coherente y uniforme, suelo partir de un proyecto base que ya tiene la estructura de archivos y patrones de diseño que quiero aplicar, con módulos de ejemplo y cualquier utilidad que pueda ser de ayuda. Por ejemplo, este repo es el que utilizaría para un proyecto en NextJS simple.

Le doy mucha importancia a que el código que genere la IA siga los patrones de diseño, organización del código, estilos, etc. que a mi me gusta. En este aspecto soy bastante riguroso con no perder la mantenibilidad del código y que la forma de desarrollar sea lo más parecida posible a la que yo seguiría.

He descubierto que Cursor es muy bueno imitando código y siguiendo la forma de programar que le indiques. Por esta razón, veo muy interesante tener en este proyecto base algunos módulos de ejemplo, de diferentes casos de uso comunes. Contando con esto, le puedes pedir a Cursor que implemente cierto requerimiento y preste atención a como ha sido implementado en tal módulo (pasándole como referencia la carpeta en la que se encuentra dicho módulo). ¡Es impresionante como es capaz de adaptarse y seguir el mismo estilo de programación!

Usar .cursorrules

Otro punto muy importante es el fichero .cursorrules. Este es un fichero especial que Cursor entiende y que utiliza para mandar instrucciones específicas a los modelos. Este archivo es útil para definir reglas y convenciones de código específicas, de modo que Cursor mantenga consistencia en el estilo y forma de programar.

Sí que es cierto que aplicando la metodología mencionada en el punto anterior ya conseguirás que el código generado siga el estilo que quieres, al pedirle que se fije en cierto código que ya tengas. En cualquier caso, es interesante contar con este fichero con las reglas que deseas para garantizar que las siga.

Dejo por aquí este repo que contiene ficheros .cursorrules para diferentes tipos de proyectos o arquitecturas que se quiera emplear. Muy interesante como punto de partida aunque siempre es conveniente adaptarlo mejor a la forma en la que quieras trabajar.

Empezando a trabajar

En este punto ya tenemos todas las herramientas necesarias para empezar a desarrollar funcionalidad. Ahora ya es cuestión de iterar paso a paso y en cada iteración dejar muy claro a la IA lo que quieres hacer y en que se tiene que basar para conseguirlo. Vamos a ver algunos ejemplos de proyectos reales en los que estoy trabajando.

Creando un nuevo módulo

En este primero ejemplo vemos como agregar un nuevo módulo al proyecto. Como podemos ver, hacemos referencia a un fichero web.md, que ya hemos construido en la fase inicial como explicamos anteriormente (con la conversación con ChatGPT) y que contiene un funcional bastante detallado del funcionamiento de la web. Además, hacemos referencia a un módulo example, que contiene, en este caso, un ejemplo de pantalla en un proyecto NextJS, con componentes típicos que suelen existir y siguiendo el estilo de programación que a mi me gusta. Finalmente, le explico muy brevemente la funcionalidad que este nuevo módulo debe contener (aunque esto ya lo tendrá en el fichero web.md mucho más detallado).

El resultado de esto es una nueva carpeta llamada contacts conteniendo todos los ficheros necesarios que implementan la funcionalidad requerida. Es muy esperable que el resultado no sea perfecto en la primera iteración. Con el resultado que te de, tienes dos formas de proceder:

Seguir la conversación y exlicarle que debe corregir para que vaya mejorando y ajustando lo que sea necesario.
Coger tu mismo el control y ajustar directamente el código que te ha generado.

Depende de cada caso concreto será más interesante una opción u otra.

Agregando funcionalidad a un módulo

En este otro ejemplo lo que estamos haciendo es agregar funcionalidad a un módulo ya existente, en este caso lo que llamamos bot. Lo que se desea es implementar un nuevo Cron que envíe recordatorios por un bot de telegram. Como vemos, le pasamos como referencias un fichero que contiene la arquitectura del proyecto, le pasamos el fichero con los esquemas de Prisma y además la carpeta del módulo donde tiene que operar. Con esto la IA tendrá un contexto muy claro tanto de la base de datos como del requerimiento a desarrollar. El resultado de esto hará lo siguiente:

Buscar en bot donde se está implementando los Crons y agregar uno nuevo.
Crear un nuevo servicio de envío de recordatorios.
Implementar el método para la recuperación de los usuarios y realizar el correspondiente envío del mensaje, apoyándose en funcionalidad ya existente si se diera el caso.
Modificar el esquema de la base de datos para guardar en el User un campo que nos permita tener su id de telegram para poder enviarle el mensaje.

Requerimientos diversos

Cabe destacar que no hay una técnica mágica que podamos aplicar en todos los casos. Cada requerimiento necesitará de un tipo de información u otra. Hay veces que es más importante darle cierta documentación, otras nos interesa más pasarle un ejemplos de código, otras nos puede interesar más referenciar a una documentación externa, etc.

Lo importante es que nosotros como desarrolladores entendamos bien el requerimiento y, en base a ello y al material del que disponemos, decidamos cual es la mejor forma de darle a la IA lo que necesita para implementarlo. Creo que es algo que a base de experiencia y práctica se va mejorando y vas siendo capaz de entender cual es la mejor forma de operar en cada caso.

Chat VS Composer

Una de las formas más efectivas para avanzar en el desarrollo con Cursor es utilizando Composer. Todos los ejemplos que veíamos en el apartado anterior eran con Composer. Esta funcionalidad permite que Cursor trabaje con todos los archivos del proyecto, proponiendo la creación, edición o eliminación de los mismos, para conseguir lo que se le pida. Es la forma más efectiva de avanzar y la que uso en casi todas las ocasiones. Aunque, como ahora te explico, hay veces que me resulta más interesante utilizar Chat.

Importante mencionar que, cuando uses Composer, es muy buena idea tener el repo limpio, sin cambios por commitear. Esto nos permite tener una visual muy clara de los cambios que Composer va proponiendo. Así puedes fácilmente revisar su propuesta y/o ajustar lo que necesites.

Por otro lado tenemos Chat, que es más ideal para resolver dudas, cuando no entiendes como funciona algo de tu código o incluso preguntas generales (aunque yo para esto prefiero tener ChatGPT en segundo plano). En principio, no es el mejor camino para avanzar el desarrollo como tal, aunque sí hay casos que es interesante. Cuando necesitas desarrollar cierta funcionalidad que sabes que puede ser especial, que se sale un poco de las funcionalidades más comunes y que, por tanto, prefieres tener mayor control sobre lo que la IA hace. En estos casos, utilizar Chat en lugar de Composer suele ser una buena idea. La forma de trabajar en cuanto a los prompts y la comunicación con la IA será la misma, pero iremos viendo el resultado que nos propone, analizando cada paso y aplicando (o no) lo que nos sugiera.

Modelos a utilizar

Por lo general, el modelo que mejores resultados da para tareas de programación es Claude 3.5. Por esta razón, considero que este debe ser el modelo que se utilice en Composer. En cuanto a Chat, sí que veo interesante utilizar otro modelo, por ejemplo gpt-4o o gpt-4o-mini. Como comentábamos en el apartado anterior, Chat se utilizará principalmente para resolver dudas generales o tareas que no impliquen desarrollar código como tal. En estos casos veo interesante no consumir los créditos de Claude y reservarlos para Composer.

Ahora bien, cuando abordamos un "evolutivo controlado" usando Chat, como comentábamos en el apartado anterior, sería interesante seguir usando Claude.

Actualización continua de la documentación

Es fundamental actualizar la documentación a medida que avanzamos en el desarrollo. Como sabemos, en el desarrollo de software las cosas pueden ir cambiando a medida que avanzamos. Reflejar el estado actual en la documentación que tenemos es vital. Tenemos que pensar que la documentación es la única forma que tenemos que de la IA esté al tanto de lo que estamos haciendo y queremos hacer. Y que para que lo haga correctamente tenemos que ser capaces de darle esta información.

Por ello, es importante estar revisando cada poco esta documentación y actualizando lo que sea necesario. La buena parte de esto, es que también le puedes pedir a Cursor que realice esta tarea por ti. Como está avanzando en el desarrollo contigo, en cada paso va a ser capaz de detectar si cierta parte de la documentación ha quedado desactualizada y que por tanto, la debe actualizar en consecuencia.

Herramienta Git Diff de Cursor

Otra práctica que suelo realizar, es la de mantener un fichero de cambios, el típico CHANGELOG.md. Con cada nueva funcionalidad que saquemos, es importante actualizar este fichero, reflejando los cambios que se han ido haciendo en el proyecto. Para esto, Cursor nos ofrece otra herramienta muy interesante que permite meter en el contexto del prompt los cambios que haya en el repo. Se accede a ella como @Git y te permite especificar contra que commit o rama quieres comparar. Yo lo que suelo hacer es, cuando he finalizado un evolutivo y estando en la rama correspondiente, le pido que analice los cambios comparando contra la rama principal (Diff With Main Branch) y que actualice el fichero correspondiente:

Cuando realice esta actualización, la rama estaría lista para mergear y podríamos dar dicho evolutivo por finalizado.

Un cambio a la vez

Es importante no pedir a Cursor que implemente múltiples evoluciones al mismo tiempo. Trabajar en un solo requisito por iteración evita errores y garantiza que la IA no genere "alucinaciones" o comportamientos inesperados. Con este método, Cursor se enfoca en un único objetivo, logrando una implementación más precisa y confiable.

¿Qué pasa con la UI?

Puede que en este punto te hayas preguntado cómo controlamos el diseño de la plataforma. Las técnicas que hemos comentado harán que deleguemos en la IA como debe ser la UI de la plataforma. Esto, obviamente, no es lo que querremos, si no tener la capacidad de controlar este aspecto.

Lo normal en cualquier desarrollo, es que se cuente con un diseño que haya que seguir, con un Figma, un XD, o la herramienta que sea. Y que utilicemos la información que esta nos da para implementar el diseño exactamente como se nos indica. Por tanto, lo ideal es que la IA cuente también con esta información para que la pueda utilizar igual que haríamos nosotros como desarrolladores.

Este es un tema en el que se está trabajando mucho. Por ejemplo, en este hilo del foro de Cursor hablan sobre ello y sobre como poder integrar Figma en Cursor. Yo he estado investigando y probando varias cosas y, al final, el mejor enfoque que he encontrado, a día de hoy, es el que indico a continuación.

Documento de material gráfico

Primero, contar con una pieza más de la documentación que sean las especificaciones gráficas. Cosas como colores a utilizar, espaciados, tamaños, etc. Todo aquello que venga definido por nuestro material gráfico y que pueda ser explicado con palabra, lo meteríamos en un doc específico.

Capturas de pantalla

Por otro lado, el uso de capturas de pantalla. Cursor también admite imágenes. Cuando le estemos pidiendo un evolutivo que implique desarrollar nueva UI, podemos adjuntarle al prompt una captura del diseño que debe contener. Esto hará que la IA tenga una buena base sobre la que trabajar la UI que deseamos.

Propiedades como contexto

Y por último, una técnica que he probado y que da buenos resultados es la que explican en este vídeo. Básicamente, consiste en utilizar un Plugin para Figma que te permite exportar las propiedades de aquel componente que tengas seleccionado. Esta información se la puedes dar a Cursor como contexto del Prompt y pedirle que implemente el componente siguiendo dichas especificaciones. Podéis ver en el vídeo que el resultado es muy bueno.

Fin

Espero que este artículo te sea útil y te inspire a mejorar tu flujo de trabajo con Cursor. Mantener la documentación organizada, partir de un proyecto base, y seguir todas las técnicas que hemos visto, son algunas de las claves para aprovechar al máximo esta herramienta y mejorar la productividad en el desarrollo de tus aplicaciones.

Si tienes alguna duda o quieres compartir tu experiencia usando Cursor, no dudes en dejar un comentario abajo. Me encantaría conocer tu opinión y saber cómo estás aprovechando esta herramienta en tu día a día como desarrollador.

Arquitectura Hexagonal con Typescript y pnpm

Enol Casielles — Fri, 25 Oct 2024 05:13:06 +0000

En un articulo anterior Cómo crear un Monorepo con TypeScript y pnpm, exploré el proceso de configuración de un monorepo usando pnpm y TypeScript. Este enfoque permite gestionar múltiples paquetes dentro de un mismo proyecto, garantizando una estructura más organizada y fácil de mantener a medida que el código crece.

Ahora, vamos un paso más allá aplicando el concepto de Arquitectura Hexagonal dentro de este monorepo. Este patrón, también conocido como "Arquitectura de Puertos y Adaptadores", nos permite crear aplicaciones modulares y desacopladas, donde la lógica de negocio se mantiene independiente de detalles de implementación, como la base de datos o el framework de la aplicación.

¿Por qué una arquitectura hexagonal?

La principal ventaja de la arquitectura hexagonal es la independencia de las capas. En este enfoque, la lógica de negocio está en el centro de la arquitectura, sin estar acoplada a la infraestructura externa como bases de datos, API externas o frameworks. Los componentes externos, como las bases de datos o los controladores HTTP, actúan como adaptadores conectados a los puertos definidos en la capa de negocio.

Ventajas clave de la arquitectura hexagonal:

Desacoplamiento: Separa claramente la lógica de negocio de las infraestructuras y dependencias externas.
Testabilidad: Facilita la creación de pruebas unitarias al aislar la lógica de negocio de los detalles de implementación.
Escalabilidad: Añadir nuevas funcionalidades o cambiar componentes es mucho más sencillo, ya que las diferentes partes del sistema no dependen directamente unas de otras.

Monorepo y Arquitectura Hexagonal: Un enfoque eficiente

Usar un monorepo para implementar una arquitectura hexagonal tiene varias ventajas. Al gestionar las diferentes capas como paquetes independientes, nos aseguramos de que cada uno mantenga su propia responsabilidad y que las dependencias entre ellas estén claramente definidas. Esto nos permite escalar el proyecto sin temor a crear dependencias circulares o acoplamientos no deseados.

Proyecto de ejemplo

Antes de entrar en detalle sobre la arquitectura, quiero explicar brevemente el proyecto de ejemplo que he construido para ilustrar este concepto. Este proyecto es un gestor de una tienda online, que incluye la gestión de productos y usuarios. Por un lado, contamos con una API para realizar operaciones CRUD sobre los productos y usuarios. Por otro lado, creamos una web que permite a los usuarios acceder a su cuenta para visualizar o gestionar su catálogo de productos.

La API se construye utilizando NestJS mientras que la web se implementa en NextJS. Veremos como el uso de esta arquitectura nos permite fácilmente reutilizar piezas de código entre ambos proyectos.

Puedes acceder directamente al repositorio del proyecto para ver la implementación realizada

Implementación

He organizado las capas de la arquitectura hexagonal en tres paquetes independientes dentro del monorepo:

Domain

Este paquete define las entidades del sistema, que representan los objetos clave del dominio, como User o Product. Además, aquí se encuentran los modelos que estructuran la comunicación entre las diferentes partes del sistema, así como los contratos de los repositorios que establecen cómo deben comportarse las implementaciones. Esta capa es totalmente independiente, sin dependencias de otros paquetes, y actúa como el núcleo de la aplicación.

Application

Esta capa define la lógica de negocio, también conocida como los casos de uso de la aplicación. Aquí se encuentran todas las operaciones que la aplicación puede realizar, como la creación, actualización, eliminación y búsqueda de productos y usuarios. Cada caso de uso actúa como un orquestador que coordina las entidades y las reglas de negocio para cumplir con una operación específica. Esta capa depende de Domain para acceder a las entidades y los contratos de los repositorios, pero no conoce las implementaciones concretas de estos repositorios. Esto permite cambiar las implementaciones sin afectar la lógica de negocio.

Database

Este paquete implementa la conexión con la base de datos y proporciona las clases concretas que cumplen con los contratos definidos en Domain. Aquí se encapsulan todos los detalles de cómo interactuar con la base de datos, incluyendo consultas, almacenamiento y recuperación de información. He optado por usar Prisma como librería ORM para dicha gestión con todas las operaciones que conlleva, como migraciones, definición del esquema, etc. Es este paquete el que se encarga de encapsular toda esta implementación.

Aplicaciones api y web

Ahora vamos a ver las 2 aplicaciones que he creado para poner a prueba la arquitectura, como comentaba anteriormente.

API (NestJS)

Esta aplicación NestJS depende de los tres paquetes anteriores (domain, application y database). Aquí es donde la magia ocurre: mediante providers y el uso de factories, se inyectan las dependencias a los casos de uso definidos en application, pasando como contexto las implementaciones concretas de los repositorios de database. Un ejemplo de cómo se implementa esto en el módulo de productos (products.module.ts):

@Module({
  controllers: [ProductsController],
  providers: [
    ProductsService,
    {
      provide: CreateProductUseCase,
      useFactory: () =>
        new CreateProductUseCase({
          productsRepository: DI.productsRepository,
        }),
    },
    // Otros casos de uso
  ],
})
export class ProductsModule {}

Aquí usamos useFactory para controlar la inyección de dependencias, garantizando que el repositorio correcto sea pasado a los casos de uso. La constante DI se encarga de la inversión de dependencias, relacionando la implementación de cada repositorio realizada en database con el contrato que cada caso de uso exige cumplir para sus dependencias.

import { ProductsRepository, UsersRepository } from '@marketplace/database';

export const DI = {
  usersRepository: new UsersRepository(),
  productsRepository: new ProductsRepository(),
};

Web (NextJS)

La aplicación NextJS se encarga de implementar la web que utilizará el usuario para interactuar con el sistema. Las páginas, utilizando el concepto de SSR que NextJS nos proporciona, se renderizan en el servidor antes de enviarlas al cliente, asegurando una mejor experiencia de usuario. Similar a la API, también se apoya en los casos de uso definidos en application para manejar la lógica de negocio desde el lado del servidor, lo cual permite reutilizar la lógica central de la aplicación tanto en la web como en la API, asegurando consistencia y un mantenimiento más sencillo.

Lo interesante de este enfoque es la reutilización de lógica entre ambas aplicaciones. En web, tenemos una pantalla que muestra el listado de productos del usuario, mientras que en API hay un endpoint que devuelve ese mismo listado. Ambas aplicaciones disparan el mismo caso de uso definido en el paquete application y utilizan la misma implementación del repositorio que se define en database, gracias a la constante DI.

Aquí un ejemplo del código en web, donde se usa el caso de uso para obtener los productos del usuario:

import { GetProductsUseCase } from "@marketplace/application";
import { DI } from "@/di";
import getUserId from "@/app/utils/get-user-id";
import handleActionsError from "@/app/utils/handle-actions-error";

export const getProductsAction = async () => {
  return handleActionsError(async () => {
    const userId = await getUserId();
    return await new GetProductsUseCase({
      productsRepository: DI.productsRepository,
      usersRepository: DI.usersRepository,
    }).execute({ userId: userId, query: {} });
  });
};

Mientras que en la API, el controlador de NestJS invoca el mismo caso de uso desde el servicio:

async getProducts(userId: string, query: GetProductsRequest) {
  const response = await this.getProductsUseCase.execute({
    userId,
    query,
  });
  return response;
}

Inyección de dependencias con DI

Para manejar la inversión de dependencias, he centralizado las instancias de los repositorios en una constante DI, donde se crean las instancias de los repositorios de usuarios y productos. De esta manera, mantenemos el control sobre las dependencias y podemos asegurar que todo esté correctamente vinculado:

import { ProductsRepository, UsersRepository } from '@marketplace/database';

export const DI = {
  usersRepository: new UsersRepository(),
  productsRepository: new ProductsRepository(),
};

Esta estrategia de centralización facilita la escalabilidad del sistema, ya que, en caso de cambios o nuevas dependencias, solo es necesario ajustar la constante DI sin tocar el resto de la aplicación.

Conclusión

La combinación de un monorepo y una arquitectura hexagonal no solo garantiza la independencia de las capas, sino que también facilita el desarrollo, la escalabilidad y el mantenimiento del proyecto. Además, la posibilidad de reutilizar lógica entre diferentes aplicaciones (como en este caso, entre API y web) asegura consistencia y reduce el esfuerzo de mantenimiento. El uso de NestJS y NextJS permite construir aplicaciones robustas y escalables, mientras que el patrón hexagonal asegura que la lógica de negocio permanezca intacta y desacoplada de las implementaciones concretas.

Puedes encontrar la implementación detallada en el siguiente repositorio de GitHub: next-nest-clean-arquitecture

Marco de Trabajo para la Creación de Agencias de Inteligencia Artificial

Enol Casielles — Mon, 27 May 2024 17:24:47 +0000

En la actualidad, el avance vertiginoso de la tecnología ha colocado a la inteligencia artificial (IA) como un pilar fundamental en diversas industrias, desde la atención médica hasta la automatización industrial. Sin embargo, conforme la IA se integra más en nuestros sistemas y procesos cotidianos, surge la necesidad de estructuras más sofisticadas que no solo gestionen tareas individuales, sino que coordinen múltiples funciones de IA de manera eficiente y efectiva.

Es aquí donde entra en juego el concepto de las Agencias de IA, una idea destinada a fomentar la colaboración y la sinergia entre diferentes agentes de IA. Estas agencias no son simplemente conjuntos de algoritmos trabajando en paralelo; son sistemas integrados diseñados para que múltiples asistentes interactúen, aprendan y se optimicen mutuamente en tiempo real. Este enfoque no solo amplía las capacidades de cada agente individual, sino que transforma la manera en que podemos utilizar la IA para abordar problemas complejos y multifacéticos.

En este artículo, exploraremos este concepto y plantearemos una solución en Typescript que permita la construcción y gestión de este tipo de agencias, permitiendo la personalización y la comunicación efectiva entre los asistentes.

Motivación del proyecto

El mundo de la IA avanza a pasos gigantescos. Cada día aparecen nuevos modelos, herramientas, estudios de investigación, etc. Una de las vertientes que está ganando cada vez más fuerza es el concepto de Agentes que interactúan entre sí. Actualmente existen varios proyectos de código abierto que han implementado esta solución y que están totalmente a nuestro alcance para ser utilizados. Algunos de los más conocidos son el proyecto AutoGen de Microsoft, el framework CrewAI o Agency Swarm, que es desarrollado por el creador de contenido VRSEN, quien está sacando vídeos continuamente acerca de este enfoque de agencias de IA. El proyecto que desarrollaremos en este tutorial coge muchos de los conceptos que se aplican en este último framework.

Entonces, si sabemos que existen varias herramientas a nuestro alcance, ¿qué sentido tiene desarrollar un "mini framework" que haga algo parecido a estas herramientas? Simplemente, por entender los conceptos y el funcionamiento interno de estas tecnologías. Si estás buscando utilizar una solución basada en agencias de IA para tu proyecto te recomiendo encarecidamente que utilices alguna de estas herramientas. Si por el contrario buscas, al igual que yo, entender como se puede construir algo así, te animo a que sigas adelante con el artículo donde veremos y explicaremos todo en detalle.

Dicho lo cual, vamos al lío 🚀

Concepto de Agencia de IA

Una Agencia de IA es una estructura compleja diseñada para coordinar y optimizar la interacción entre múltiples asistentes de inteligencia artificial. Este marco de trabajo integra varios componentes clave que permiten una funcionalidad avanzada y una colaboración efectiva entre los agentes. A continuación, describiremos cada uno de estos componentes y su función dentro de la agencia:

Agente (Agent)

Un agente es un asistente de IA que realiza tareas específicas basadas en una descripción detallada de sus responsabilidades y las instrucciones de cómo llevarlas a cabo. Cada agente puede equiparse con diversas herramientas personalizadas para expandir su capacidad de acción más allá de sus funciones predeterminadas. En nuestra implementación, utilizaremos los asistentes de OpenAI.

Misión

La agencia también definirá una misión, que podemos considerar como unas instrucciones globales. Todo agente será consciente de la misión de la agencia, para que sepa el objetivo final de lo que hace.

Herramienta (Tool)

Las herramientas son extensiones funcionales que permiten a los agentes realizar tareas que exceden sus capacidades iniciales. Estas pueden incluir acciones como enviar correos electrónicos, realizar búsquedas en la web o crear y almacenar documentos. Al definir una herramienta, se especifica su funcionalidad, lo que puede hacer y los parámetros necesarios para su ejecución. Toda herramienta contará con un método run, donde se implementa la tarea asignada. Finalmente, las herramientas se asignarán a los agentes, quienes comprenderán su funcionamiento y las utilizarán cuando sea necesario. Con "utilizarlas" nos referimos a invocar el método run con los parámetros necesarios.

Hilo (Thread)

Para facilitar la comunicación entre agentes, se define el concepto de "hilos". Estos son objetos que contienen un agente emisor y otro receptor, funcionando como canales por los cuales los agentes pueden interactuar entre sí. Al crear una agencia, además de especificar los agentes que la conforman, se deberá definir las comunicaciones que pueden existir entre ellos. Los hilos serán los encargados de registrar esta información.

Herramienta TalkToAgent

TalkToAgent es una herramienta especial que se cargará por defecto en los agentes que lo requieran. Su propósito es facilitar la iniciación de diálogos entre agentes. Cada agente podrá y utilizará esta herramienta cuando deduzca que debe comunicarse con otro. Para ello, indicará como parámetros el agente destinatario y el mensaje a transmitir. La implementación del método run de esta herramienta buscará el hilo apropiado que conecta a ambos agentes y enviará el mensaje especificado. De esta forma, conseguimos que los agentes tengan la capacidad de comunicarse entre sí.

Usuario

Dentro de la agencia también existe un "agente usuario", una representación especial del usuario humano que interactúa con la agencia. Este agente no estará asociado a un asistente de OpenAI, pero formará parte de los hilos que correspondan como emisor, habilitando así la interacción del usuario con los diferentes agentes que corresponda.

Estas son las diferentes partes que implementará el marco de trabajo. Con ello, para crear una agencia, se comienza por definir y configurar los agentes individuales, especificando su rol particular y las instrucciones para desempeñar las tareas que deban realizar. Asimismo, se define la misión de la agencia. A continuación, se asigna a cada agente un conjunto único de herramientas que complementan y expanden sus capacidades intrínsecas. Posteriormente, se definen las comunicaciones posibles entre los diferentes agentes, habilitando así los diferentes hilos de comunicación que permiten una interacción entre ellos de manera coordinada, compartiendo información y colaborando en tareas complejas. También se especificará con qué agentes podrá comunicarse el usuario. Con todo ello, la agencia está lista para empezar a trabajar. Un simple mensaje del usuario a uno de los agentes pondrá todo en marcha.

Requisitos del Proyecto

Habiendo explicado el concepto de Agencia de IA y lo que se requiere para hacerla funcionar, a continuación definiremos algunos requisitos que nuestro software debe cumplir para que podamos utilizarlo y extenderlo de manera robusta y eficiente:

Interfaz Web: Necesitamos una interfaz web que permita visualizar toda la comunicación entre cada Agente y habilite al usuario a comunicarse con aquellos agentes pertinentes.
API Rest: Debe existir una API Rest que permita consumir la información de la agencia e interactuar con ella. La interfaz web utilizará esta API para obtener todos los datos necesarios y enviar los mensajes del usuario.
Separación de Módulos: Es fundamental que los módulos estén completamente separados, diferenciando claramente la implementación base de la agencia con la definición de una agencia específica. Un módulo se encargará de implementar las bases, mientras que otro módulo consumirá esta implementación base y creará la agencia. Esto es crucial para permitir la creación de diferentes agencias dentro del mismo marco de manera sencilla, lo que nos brindará la capacidad de probar diferentes enfoques de manera ágil y efectiva.
Persistencia de Datos: En caso de que la aplicación se reinicie, es necesario que el estado anterior se mantenga, incluyendo los agentes creados, los hilos, los mensajes, etc. No queremos que cada vez que iniciemos el proyecto, todo se construya desde cero.

Arquitectura del Marco de Trabajo

Para cumplir con los requisitos anteriores, hemos optado por la siguiente arquitectura:

Monorepo con Typescript y pnpm

La modularidad es importante y buscamos un entorno de trabajo ágil y eficiente. Por ello, hemos elegido una arquitectura de monorepo, similar a la que se describe en este artículo, donde se explica cómo construir un monorepo utilizando herramientas como pnpm. Además, en este caso nos apoyaremos también en la herramienta turborepo para facilitar la creación y gestión del proyecto.

Python o Typescript

Inicialmente, podría parecer lógico utilizar Python para este proyecto, dado que es el lenguaje dominante en las aplicaciones de procesamiento de lenguaje natural. Sin embargo, después de un análisis exhaustivo, hemos decidido utilizar Typescript. Las razones de esta decisión son las siguientes:

Mi experiencia y dominio en Typescript superan ampliamente a los de Python. Typescript es el lenguaje que utilizo a diario en proyectos reales y de gran alcance, mientras que mi experiencia con Python se limita a pequeños proyectos de exploración.
Aunque Python es dominante en este ámbito, Typescript no está dejado de lado. Herramientas como LangChain, LlamaIndex y la API de OpenAI cuentan con soporte para Typescript.
El uso de Typescript simplifica la implementación de la arquitectura propuesta basada en un entorno de monorepo. Integrar Python en este ecosistema nos complicaría las cosas.

A pesar de estas razones, aún tengo dudas y no descarto la posibilidad de migrar el marco de trabajo a Python en el futuro, como una oportunidad para aprender y familiarizarme más con este lenguaje.

Interfaz de Usuario con Next.js

La aplicación web principal en el monorepo, denominada web, se desarrollará utilizando Next.js. Su función principal será facilitar la interacción del usuario con la agencia y permitirle visualizar de manera organizada la comunicación entre los diferentes agentes. En esta primera versión, la aplicación mostrará simplemente los "hilos" de comunicación entre agentes, lo que permitirá visualizar los mensajes intercambiados. Además, cuando el usuario sea el emisor de un hilo, se le dará la posibilidad de enviar mensajes al agente receptor. Esta funcionalidad no solo mejora la interactividad, sino que también proporciona un seguimiento detallado de las interacciones dentro de la agencia.

Paquete `agency`

El núcleo del sistema reside en el paquete agency, donde se define la arquitectura principal de la agencia. Este paquete se encarga de implementar toda la funcionalidad de la agencia y de exponer públicamente las clases o funciones necesarias para la creación de las agencias.

Este paquete incluye las siguientes partes:

Clases Base: Se definen las clases fundamentales para la creación de un agente (Agent) y una herramienta (Tool), así como las clases para los hilos (Thread) y los mensajes (Message) que facilitan la comunicación entre agentes.
Clase Agencia: Se presenta como una clase abstracta. En ella se implementa la funcionalidad necesaria para la ejecución de la agencia, pero se delega a quien la extienda los siguientes aspectos:
- Definición de los agentes que conforman la agencia.
- Definición de las diferentes comunicaciones que puede existir entre los diferentes agentes.
- Definición de una carpeta donde se pueda persistir la información de la agencia, garantizando que no se pierda su estado frente a un reinicio de la ejecución.
API Rest: Una característica destacada de nuestra agencia es que levantará un servidor Express para permitir la interacción con sus objetos a través de una API, facilitando así el acceso a sus datos o la interacción con ella. La aplicación web se conectará a esta API para comunicarse con la agencia.
Server Sent Events: La aplicación web necesitará poder recibir los mensajes que se van generando y mostrarlos según se produzcan. Por ello, además de la API Rest, necesitamos un mecanismo que permita el envío de datos del servidor al cliente. Para resolver esto, hemos optado por implementar Server Sent Events. Cuando la web cargue un hilo, habilitará un mecanismo de escucha. Cuando la agencia genere un nuevo mensaje, lo emitirá al cliente a través de este mecanismo. De esta forma, mantenemos los mensajes actualizados y en tiempo real en la web.
OpenAI: Como se mencionó anteriormente, para interactuar con el LLM utilizaremos directamente la API de OpenAI. Cada agente creará un asistente de OpenAI a través del cual se comunicará con otros agentes.

Implementación de la Agencia

Con el paquete agency disponible, solo nos queda utilizarlo para definir las agencias que deseemos. Para ello, habilitaremos una nueva aplicación en el monorepo que llamaremos back, la cual tendrá una dependencia con este paquete agency. En este artículo, no profundizaremos en esta parte, ya que nuestro objetivo es explicar los fundamentos para la creación de las agencias, no su definición detallada. En artículos posteriores, utilizaremos esta base para crear diferentes agencias capaces de resolver problemas reales.

Implementación de la app `web`

No profundizaremos en la explicación de esta parte en particular. Se trata de un proyecto Next muy sencillo que consta de una única pantalla. En esta pantalla, se presenta un menú lateral que lista todos los hilos de comunicación, mientras que a la derecha se muestran los mensajes del hilo seleccionado. Este proyecto utiliza un servicio para realizar llamadas a la API y obtener los datos necesarios.

Cuando la pantalla de un hilo se carga, se verifica si el usuario forma parte de dicho hilo. En caso afirmativo, se habilita un campo de texto en la parte inferior junto con un botón de enviar, lo que permite al usuario enviar mensajes en ese hilo específico.

La implementación se encuentran disponibles en el repositorio de GitHub mencionado al final del artículo. Sin embargo, dado que este tema se aleja del propósito principal de este artículo, considero que no es necesario profundizar en los detalles de esta implementación.

Implementación del paquete `agency`

Vamos a examinar en detalle cómo se implementa el núcleo de una agencia, así como las diferentes partes que lo componen y cómo se relacionan entre sí.

Clase User

La clase User representa una entidad con capacidad de comunicación en el sistema. Esto puede ser tanto un agente de IA como el usuario real que utiliza la agencia. Los agentes extienden esta clase User, que es un modelo simple con propiedades id y name.

export class User {
  constructor(
    public id: string,
    public name: string,
  ) {}
}

El usuario real se representa como una instancia de esta clase.

Agent

La clase Agent sirve como base para la creación de los agentes que componen la agencia. Esta clase tiene propiedades para definir las diferentes características de un agente, como su nombre, instrucciones o las herramientas que se le asignan. Además, cuenta con un método principal que llamamos init, donde se lleva a cabo la inicialización del asistente asociado en OpenAI.

  async init() {
    if (this.id) {
      let openAiAssistant = await openaiClient.beta.assistants.retrieve(
        this.id,
      );
      const shouldUpdate = this.shouldUpdate(openAiAssistant);
      if (shouldUpdate) {
        openAiAssistant = await openaiClient.beta.assistants.update(
          this.id,
          this.generateBody() as AssistantUpdateParams,
        );
      }
      this.assistant = openAiAssistant;
      if (shouldUpdate) this.delegate.onUpdateAgent(this);
    } else {
      this.assistant = await openaiClient.beta.assistants.create(
        this.generateBody() as AssistantCreateParams,
      );
      this.id = this.assistant.id;
    }
  }

Este método determina si el agente tiene asignado un ID, lo que indica si ya existe en OpenAI. Si existe, se recupera; de lo contrario, se crea uno nuevo. Además, emplea el método privado shouldUpdate para verificar si es necesario actualizarlo. Esto es crucial para garantizar que los cambios realizados en el agente, como la actualización de sus instrucciones, se reflejen en el asistente de OpenAI. Del mismo modo también asegura que no se estén creando nuevos asistentes cada vez que la aplicación arranca.

Una característica destacada de la clase Agent es su uso del patrón Observer para notificar a otros objetos sobre ciertos eventos. Específicamente, se notifica cuando se actualiza el agente en OpenAI. Más adelante, veremos como la clase Agency actuará como el delegado u observador, utilizando este evento para llevar a cabo acciones específicas.

Message

Una parte sencilla pero importante de nuestro sistema es la clase Message, que representa cada uno de los mensajes que se generan durante la ejecución. Es una clase modelo con las propiedades que queremos registrar.

export class Message {
  id: string;
  date: Date;
  type: MessageType;
  content: string;
  from: User;
  to: User;

  constructor({ id, date, type, content, from, to }: Props) {
    this.id = id;
    this.date = date;
    this.type = type;
    this.content = content;
    this.from = from;
    this.to = to;
  }
}

Tool

Definimos la clase Tool para representar las diferentes herramientas que se asignan a los agentes para dotarles de funcionalidades. Por un lado define las propiedades que OpenAI necesita para la creación de la herramienta: el nombre, la descripción y la definición de los parámetros que puede recibir. Por otro lado define un método abstracto runque será el que cada Tool deberá implementar para ejecutar las tareas que deba realizar. Como veremos más adelante, el sistema estará preparado para que, cuando un agente deduzca que una herramienta ha de ser ejecutada, se invoque este método run en ella con los parámetros que el agente nos indique.

export abstract class Tool {
  name: string;
  description: string;
  parameters: any;

  constructor({ name, description, parameters }: ToolParams) {
    this.name = name;
    this.description = description;
    this.parameters = parameters;
  }

  abstract run(parameters: RunProps): Promise<string>;
}

Thread

La clase Thread es fundamental en el sistema, ya que facilita la comunicación entre agentes permitiendo el intercambio de mensajes entre ellos. Esta clase es responsable de interactuar con OpenAI para enviar mensajes y gestionar las respuestas recibidas.

Destacan varias propiedades en esta clase, entre las que se encuentran senderAgent y recipientAgent, que son objetos que representan los dos agentes (o usuarios) involucrados en la comunicación. Además, cuenta con la propiedad messages, que es una lista de objetos de tipo Message y se utiliza para almacenar los mensajes generados durante la comunicación.

En cuanto a los métodos, por un lado tenemos init, el cual se encarga de inicializar el Thread en OpenAI. Al igual que con los agentes, este método utiliza la propiedad id para determinar si el registro ya existe y solo necesita ser recuperado, o si, por el contrario, no existe y debe crearse en OpenAI. Veremos más adelante como Agency creará estos objetos Thread con id o no, para indicar si ya existe o no en función de la información que tenga en su capa de persistencia.

  async init() {
    if (this.id) {
      this.thread = await openaiClient.beta.threads.retrieve(this.id);
    } else {
      this.thread = await openaiClient.beta.threads.create();
      this.id = this.thread.id;
    }
  }

Por otro lado tenemos el método send. Este método es el que se llama cada vez que se debe enviar un mensaje a recipientAgent.

  async send(message: string, retries: number = 1): Promise<string> {
    if (!this.recipientAgent.id) throw new Error("Recipient agent not set");
    if (!this.thread) await this.init();
    await openaiClient.beta.threads.messages.create(this.id, {
      role: "user",
      content: message,
    });
    this.run = await openaiClient.beta.threads.runs.create(this.id, {
      assistant_id: this.recipientAgent.id,
    });
    this.addNewMessage(MessageType.Text, message);
    while (true) {
      await this.waitUntilDone();
      if (this.run.status === "completed") {
        const _message = await this.extractMessage();
        this.addNewMessage(MessageType.Text, _message, true);
        return message;
      } else if (this.run.status === "requires_action") {
        await this.processAction();
      } else {
        const err = "Run failed: " + this.run.status;
        console.log(err);
        if (retries < MAX_RETRIES) {
          console.log("Retrying in 30s...");
          await new Promise((resolve) => setTimeout(resolve, 30000));
          return this.send(message, retries + 1);
        }
        const _message = this.generateFailedMessage();
        this.addNewMessage(MessageType.Text, _message, true);
        return _message;
      }
    }
  }

Veamos detalladamente el proceso que se lleva a cabo aquí. En primer lugar, verificamos que el agente receptor esté correctamente inicializado. Luego, comprobamos si el hilo está inicializado; en caso contrario, lo inicializamos. A continuación, creamos el mensaje en el asistente de OpenAI y posteriormente creamos el objeto run, proporcionado por OpenAI, que nos permite controlar el envío del mensaje y la recepción de la respuesta.

Seguidamente, añadimos el mensaje al listado y comenzamos un bucle infinito para controlar la respuesta. Dentro de este bucle, primeramente utilizamos un método privado para verificar el estado del run y continuamos únicamente cuando tenga un estado adecuado.

  private async waitUntilDone() {
    while (["queued", "in_progress", "cancelling"].includes(this.run.status)) {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      this.run = await openaiClient.beta.threads.runs.retrieve(
        this.id,
        this.run.id,
      );
    }
  }

Cuando el run alcance un estado que nos permita manejar la respuesta, actuaremos en consecuencia. Si el estado es completed, sabemos que hemos recibido una respuesta definitiva del asistente, por lo que podemos procesarla, generar un nuevo mensaje y concluir esta ejecución. Para procesar la respuesta, nos apoyamos en otro método privado llamado extractMessage.

  private async extractMessage() {
    const messages = await openaiClient.beta.threads.messages.list(this.id);
    const content = messages.data[0].content[0];
    if (content.type === "text") {
      return content.text.value;
    } else {
      throw new Error(
        "Framework does not support messages different than text yet.",
      );
    }
  }

Sin embargo, los asistentes de OpenAI no siempre proporcionan una respuesta directa. Si han sido equipados con herramientas y durante su ejecución determinan que necesitan usar alguna de ellas, nos lo indicarán estableciendo en el run un estado con valor requires_action y nos proporcionarán todo lo necesario para llevar a cabo la acción. Cuando esto suceda, utilizaremos otro método privado llamado processAction para gestionar dicha acción.

  private async processAction() {
    const toolsToExecute =
      await this.run.required_action.submit_tool_outputs.tool_calls;
    const toolsResults = [];
    for (const toolToExecute of toolsToExecute) {
      this.addNewMessage(
        MessageType.Action,
        `Acción requerida. Ejecutando la tool ${toolToExecute.function.name} con parámetros ${toolToExecute.function.arguments}`,
        true,
      );
      const toolName = toolToExecute.function.name;
      const tool = this.recipientAgent.tools.find((t) => t.name === toolName);
      const toolResult = tool
        ? await tool.run({
            ...JSON.parse(toolToExecute.function.arguments),
            callerAgent: this.recipientAgent,
          })
        : "ERROR: no existe ninguna herramienta con el nombre que has indicado. Inténtalo de nuevo con el nombre correcto. La lista de herramientas disponibles es la siguiente: " +
          this.recipientAgent.tools.map((t) => t.name).join(", ");
      this.addNewMessage(
        MessageType.Action,
        `${toolToExecute.function.name} completada. Respuesta: ${toolResult.toString()}`,
        true,
      );
      toolsResults.push({
        tool_call_id: toolToExecute.id,
        output: toolResult.toString(),
      });
    }
    this.run = await openaiClient.beta.threads.runs.submitToolOutputs(
      this.id,
      this.run.id,
      {
        tool_outputs: toolsResults,
      },
    );
  }

Este método básicamente extrae la información de la respuesta para determinar qué herramientas deben ejecutarse. A continuación recorre cada una de estas herramientas y realiza las siguientes acciones:

Guarda el mensaje para registrar que se va a ejecutar una herramienta.
Busca esta herramienta a partir de su nombre dentro de las herramientas del agente y la ejecuta para obtener un resultado. En caso de que no encuentre la herramienta, directamente genera un resultado de error.
Guarda un nuevo mensaje para registrar el resultado de la invocación de dicha herramienta

Cuando finalice la invocación de todas las herramientas indicadas por el agente, se le envía los resultados obtenidos a OpenAI, para que el asistente sepa como ha de continuar su ejecución. Este último paso también actualizará el objeto run, lo que hará que el bucle principal pueda continuar su proceso.

Volviendo al bucle principal, también gestionamos el caso en el que el estado no sea ni completed ni requires_action. En este caso, OpenAI nos indica que ha ocurrido algún tipo de error. A veces, esto puede deberse simplemente a un mal funcionamiento de la API en ese momento. Por eso, establecemos un mecanismo de reintento. Cuando llegamos a esta parte del código, hacemos una pausa de 30 segundos en la ejecución y volvemos a intentar el proceso desde el principio. Si después de 3 intentos el problema persiste, finalizamos con un mensaje manual de error.

Para concluir, es importante mencionar que al igual que la clase Agent, la clase Thread también utiliza un patrón Observer para informar a un delegado cuando se añade un nuevo mensaje. Esto se realiza a través de la interfaz ThreadDelegate. El método privado addNewMessage utiliza este delegado para enviarle el mensaje que se acaba de registrar. Más adelante, veremos cómo la clase Agency se registrará como delegado y ejecutará ciertas acciones cuando se produzca este evento.

  private addNewMessage(type: MessageType, content: string, inverse = false) {
    const message: Message = {
      id: Math.random().toString(),
      date: new Date(),
      type,
      content,
      from: inverse ? this.recipientAgent : this.senderAgent,
      to: inverse ? this.senderAgent : this.recipientAgent,
    };
    this.messages.push(message);
    this.delegate.onNewMessage(this, message);
  }

Podemos concluir este apartado mencionando que la clase Thread es una pieza clave en nuestro sistema, ya que es donde reside toda la interacción con OpenAI para el envío de mensajes, la gestión de respuestas y la invocación de posibles herramientas.

Api

Como veíamos anteriormente, un requisito que tenemos es el de habilitar la exposición de los datos de la agencia y permitir la interacción con ella a través de una API Rest. La clase Api asume esta responsabilidad.

Esta clase se apoya en la librería Express para crear una simple API Rest con los endpoints que necesitamos. A través del constructor obligamos a que reciba la instancia de la clase Agency, que la usará para acceder a los datos de la misma. También permitimos desde el constructor elegir el puerto en el que se quiere exponer esta API.

La clase cuenta con un método initen el que se inicializará express y se definirán los diferentes endpoints.

  async init() {
    const agency = this.agency;

    const app = express();
    app.use(express.json());
    app.use(sseMiddleware);
    app.use(cors());

    app.get("/ping", async (_: Request, res: Response) => {
      try {
        res.send({ hello: "world" });
      } catch (err) {
        res.status(500).send({ error: err });
      }
    });

    app.get("/info", async (_: Request, res: Response) => {
      try {
        res.send({
          name: agency.name,
          mission: agency.mission,
          agents: agency.agents.map((agent) => ({
            name: agent.name,
            id: agent.id,
          })),
        });
      } catch (err) {
        res.status(500).send({ error: err });
      }
    });

    //-------Resto de endpoints-------

  }

Algo a destacar en esta clase es la propiedad clients, que será un listado de objetos SseClient , clase que explicamos enseguida. Esta es la forma que conseguimos habilitar una comunicación basada en Server-sent events. Anteriormente explicamos que esto es importante para poder enviar al cliente los mensajes que se vayan generando y que pueda actualizar la interfaz con cada evento. Para esto nos apoyamos en la librería express-sse-middleware que habilita un middleware de Express para el uso de esta tecnología. En el anterior init se puede ver como se inicializa este middleware. Para usar esta funcionalidad dotamos a la API de un endpoint que se encarga de crear un nuevo SseClient.

    app.get(
      "/threads/:threadId/sseClient",
      async (req: Request, res: Response) => {
        try {
          const { threadId } = req.params;
          const sseClient = new SseClient(threadId, res.sse());
          this.clients.push(sseClient);
          req.on("close", () => {
            this.removeSseClient(threadId);
          });
        } catch (err) {
          res.status(500).send({ error: err });
        }
      },
    );

La clase SseClient simplemente registra el id del Thread al que está conectado el cliente y el propio objeto que nos permite la comunicación, obtenido a partir de res.sse()

export class SseClient {
  private client: any;

  constructor(
    public threadId: string,
    client: any,
  ) {
    this.client = client;
  }

  send(data: any) {
    this.client.send(JSON.stringify(data));
  }

  close() {
    this.client.close();
  }
}

La clase SseClient cuenta con 2 métodos, uno para enviar un mensaje al cliente y otro para cerrar la comunicación.

Volviendo a la clase Api , definimos otro método sendMessage, que recibiendo el id de un Thread y el objeto Message se encarga de analizar si existe algún cliente conectado a ese hilo y, en ese caso, enviarle el mensaje. Este método es utilizado por la clase Agency para informar de los nuevos mensajes que se generan.

  sendMessage(threadId: string, message: Message) {
    if (!this.clients) return;
    const sseClient = this.clients.find(
      (client) => client.threadId === threadId,
    );
    if (!sseClient) return;
    sseClient.send({
      date: message.date,
      type: message.type,
      content: message.content,
      from: message.from.name,
      to: message.to.name,
    });
  }

Por último, la clase Api cuenta con un método removeSseClient, responsable de limpiar una conexión. Este método es ejecutado cuando el servidor detecte que un cliente finaliza la comunicación, liberando así los recursos que dejan de ser útiles. En el endpoint /threads/:threadId/sseClientque veíamos un poco más arriba, se puede ver como se llama a este método cuando se detecta un cierre en la conexión.

  removeSseClient(threadId: string) {
    if (!this.clients) return;
    const sseClient = this.clients.find(
      (client) => client.threadId === threadId,
    );
    if (!sseClient) return;
    sseClient.close();
    this.clients = this.clients.filter(
      (client) => client.threadId !== threadId,
    );
  }

Agency

En este punto, hemos delineado las diferentes partes clave que definen nuestra agencia. Ahora solo nos queda entender cómo ponerlas en funcionamiento todas juntas. La clase Agency asumirá esta responsabilidad.

La clase Agency será una clase abstracta que tendrá propiedades y métodos propios para permitir la ejecución correcta de la agencia, pero delegará a quien la utilice los detalles de la definición de dicha agencia. Esto es crucial y veremos por qué. Esta clase se encargará de tareas como iniciar los agentes, los hilos, persistir los datos, etc. Sin embargo, no queremos que esta clase tome decisiones sobre qué agentes conforman la agencia o dónde se persisten los datos. Estas son responsabilidades de la aplicación que utilice esta clase. Por esta razón, definimos 3 métodos abstractos:

El método getAgents, que deberá devolver el listado de agentes deseado.
El método getAgentCommunications, que, al pasarle un agente, debería indicarnos con qué otros agentes puede comunicarse.
El método getDBPath, que deberá devolver la ruta de una carpeta en la que la agencia podrá guardar la información necesaria para asegurar la persistencia de datos. Esto es clave ya que así esta clase gestiona la persistencia de datos pero el espacio en el que se almacenan es responsabilidad de quien la utilice.

Continuamos con las propiedades de esta clase. Por un lado, tenemos el nombre y la misión de la agencia: name y mission. Estas propiedades se pueden definir desde el constructor. La clase inicializará una instancia de User para representar al usuario que utiliza la agencia. Además, contará con propiedades para registrar el listado de agentes (Agent) o hilos (Thread). También contará con una propiedad para registrar la ruta en la que se persisten los datos, dbPath, y una instancia de la clase Api.

export abstract class Agency implements ThreadDelegate, AgentDelegate {
  name: string;
  mission: string;

  user: User;
  agents: Array<Agent>;
  threads: Array<Thread>;
  api: Api;
  dbPath: string;

  constructor({ name, mission }: AgencyParams) {
    this.name = name;
    this.mission = mission;
    this.user = new User("user", "User");
  }

  abstract getAgents(): Agent[];
  abstract getAgentCommunications(agent: User): Agent[];
  abstract getDBPath(): string;

  /**
   * --- Methods ---
   */

}

En cuanto a los métodos, comenzamos con initApi, que simplemente se encarga de inicializar la instancia de la clase Api.

  async initApi(port: number) {
    this.api = new Api(this, port);
    await this.api.init();
  }

Continuamos con el método run. Aquí será donde se lleva a cabo la definición de todas las entidades que se necesita.

  async run() {
    this.dbPath = this.getDBPath();
    this.agents = this.getAgents();
    if (!this.agents || this.agents.length === 0)
      throw new Error(
        "You can't init without defining any agents. User will talk to first defined agent",
      );
    for (const agent of this.agents) {
      agent.id = this.getSavedAgentId(agent);
      agent.setDelegate(this);
      if (this.mission)
        agent.instructions = `${this.mission}\n\n${agent.instructions}`;
      this.addCommonTools(agent);
      await agent.init();
    }
    this.threads = [];
    for (const agent of [this.user, ...this.agents]) {
      const recipientAgents = this.getAgentCommunications(agent);
      for (const recipientAgent of recipientAgents) {
        const thread = new Thread({
          id: this.getSavedThreadId(agent, recipientAgent),
          senderAgent: agent,
          recipientAgent,
          delegate: this,
        });
        thread.messages = this.getSavedMessages(thread.id);
        await thread.init();
        this.threads.push(thread);
      }
    }
    this.saveAgentsAndThreads();
  }

Básicamente lo que este método hace es inicializar los agentes y los hilos. Como comentamos, nos apoyamos en los métodos abstractos para que la aplicación nos de los detalles. También vemos como se utilizan métodos privados para comprobar si cierto agente o hilo existe ya o no, lo cual permitirá decidir si ha de crearse desde cero o usar el existente. Lo mismo para la carga de los mensajes generados en anteriores ejecuciones.

A continuación vamos a ver los métodos que se utilizan para implementar el mecanismo de persistencia de datos. Como veremos estamos guardando ficheros JSON en la carpeta que la clase hija nos ha especificado. Este mecanismo de persistencia de datos es muy básico y poco robusto. Sería mucho más interesante implementar una base de datos que registre esta información, pero por simplicidad se ha optado por esta solución. Una muy clara mejora de este proyecto es la migración de esta parte a un mecanismo basado en una base de datos convencional.

  private getSavedAgentId(agent: Agent): string {
    const agentsDataStr = this.readFileContentOrCreate(
      path.resolve(this.dbPath, "./agents.json"),
    );
    const agentsData = agentsDataStr ? JSON.parse(agentsDataStr) : [];
    const agentData = agentsData.find((a: any) => a.name === agent.name);
    return agentData ? agentData.id : null;
  }

  private getSavedThreadId(senderAgent: User, recipientAgent: User): string {
    const threadsDataStr = this.readFileContentOrCreate(
      path.resolve(this.dbPath, "./threads.json"),
    );
    const threadsData = threadsDataStr ? JSON.parse(threadsDataStr) : [];
    const threadData = threadsData.find(
      (t: any) =>
        t.senderAgent === senderAgent.id &&
        t.recipientAgent === recipientAgent.id,
    );
    return threadData ? threadData.id : null;
  }

  private getSavedMessages(threadId: string): Message[] {
    const messagesDataStr = this.readFileContentOrCreate(
      path.resolve(this.dbPath, "./messages.json"),
    );
    const messagesData = messagesDataStr ? JSON.parse(messagesDataStr) : [];
    const messages = messagesData
      .filter((m: any) => m.threadId === threadId)
      .map((message: any) => {
        const fromUser = message.from === this.user.id;
        const toUser = message.to === this.user.id;
        return new Message({
          id: message.id,
          date: new Date(message.date),
          type: message.type,
          content: message.content,
          from: fromUser
            ? this.user
            : this.agents.find((a) => a.id === message.from),
          to: toUser ? this.user : this.agents.find((a) => a.id === message.to),
        });
      });
    return messages;
  }

Cuando se ha completado la inicialización de todas las entidades, invocamos al método saveAgentsAndThreads, lo cual persiste el estado actual de los agentes e hilos, asegurando que tengamos siempre todo correctamente sincronizado.

  private saveAgentsAndThreads(): void {
    const agentsData = this.agents.map((agent) => ({
      name: agent.name,
      id: agent.id,
    }));
    fs.writeFileSync(
      path.resolve(this.dbPath, "./agents.json"),
      JSON.stringify(agentsData),
    );
    const threadsData = this.threads
      .filter((t) => t.id !== null)
      .map((t) => ({
        id: t.id,
        recipientAgent: t.recipientAgent.id,
        senderAgent: t.senderAgent.id,
      }));
    fs.writeFileSync(
      path.resolve(this.dbPath, "./threads.json"),
      JSON.stringify(threadsData),
    );
  }

Cuando estos métodos initApi y run se hayan ejecutado, la agencia estará totalmente lista para ser utilizada. Ahora entra en juego el método processUserMessage, que será el que se llamará cuada vez que un usuario se comunique con un agente.

  async processUserMessage(threadId: string, message: string): Promise<string> {
    const thread = this.threads.find((thread) => thread.id === threadId);
    if (!thread) throw new Error("Thread not found");
    if (thread.senderAgent !== this.user)
      throw new Error("User can't send message to this thread");
    return await thread.send(message);
  }

Simplemente recupera el Thread y ejecuta su método send.

Esta clase Agency también expone los métodos getThread y getAgentByName, que serán utilizados por Api para obtener un hilo o un agente.

  getThread(senderAgentName: string, recipientAgentName: string) {
    return this.threads.find(
      (thread) =>
        thread.senderAgent.name === senderAgentName &&
        thread.recipientAgent.name === recipientAgentName,
    );
  }

  getAgentByName(agentName: string) {
    return this.agents.find((agent) => agent.name === agentName);
  }

Continuamos con la implementación de las interfaces. ¿Recordáis cuando explicamos las clases Agent o Thread y mencionamos que utilizaban un patrón Observer? Pues bien, esta clase Agency será la responsable de implementar esta funcionalidad y registrarse como delegado. Si nos fijamos en el método run, cuando se crea un agente o un hilo, veremos que se envía la instancia de esta clase Agency a la propiedad delegate. Además, en la definición de la clase Agency, especificamos que implementará los métodos de ThreadDelegate y AgentDelegate. Por último, en la parte inferior de la clase, llevamos a cabo estas implementaciones. Básicamente, utilizamos este mecanismo para poder persistir los datos cuando un agente se actualiza o un hilo guarda un nuevo mensaje.

  /**
   * ThreadDelegate implementation
   */
  onNewMessage(thread: Thread, message: Message): void {
    if (!this.api) return;
    this.api.sendMessage(thread.id, message);
    const messagesDataStr = this.readFileContentOrCreate(
      path.resolve(this.dbPath, "./messages.json"),
    );
    const messages = messagesDataStr ? JSON.parse(messagesDataStr) : [];
    messages.push({
      id: message.id,
      threadId: thread.id,
      date: message.date.toISOString(),
      type: message.type,
      content: message.content,
      from: message.from.id,
      to: message.to.id,
    });
    fs.writeFileSync(
      path.resolve(this.dbPath, "./messages.json"),
      JSON.stringify(messages),
    );
  }

  /**
   * AgentDelegate implementation
   */
  onUpdateAgent(agent: Agent): void {
    const agentsDataStr = fs.readFileSync(
      path.resolve(this.dbPath, "./agents.json"),
      "utf-8",
    );
    const agentsData = JSON.parse(agentsDataStr);
    const agentData = agentsData.find((a: any) => a.id === agent.id);
    agentData.name = agent.name;
    fs.writeFileSync(
      path.resolve(this.dbPath, "./agents.json"),
      JSON.stringify(agentsData),
    );

    const threadsDataStr = fs.readFileSync(
      path.resolve(this.dbPath, "./threads.json"),
      "utf-8",
    );
    const threadsData = JSON.parse(threadsDataStr);
    const threadsDataFiltered = threadsData.filter(
      (t: any) => t.senderAgent !== agent.id && t.recipientAgent !== agent.id,
    );
    fs.writeFileSync(
      path.resolve(this.dbPath, "./threads.json"),
      JSON.stringify(threadsDataFiltered),
    );

    const messagesDataStr = fs.readFileSync(
      path.resolve(this.dbPath, "./messages.json"),
      "utf-8",
    );
    const messagesData = JSON.parse(messagesDataStr);
    const messagesDataFiltered = messagesData.filter(
      (m: any) => m.from !== agent.id && m.to !== agent.id,
    );
    fs.writeFileSync(
      path.resolve(this.dbPath, "./messages.json"),
      JSON.stringify(messagesDataFiltered),
    );
  }

Por último, hay un detalle importante que hemos pasado por alto y que vale la pena resaltar: el método privado addCommonTools. Este método se encarga de asignar a un agente las herramientas que deseemos darle por defecto. En el método run, al inicializar el agente, llamamos a este método para cargar estas herramientas. Por el momento, solo contamos con una herramienta común, llamada TalkToAgent. En la siguiente sección, la explicaremos en detalle, pero en resumen, esta herramienta permite que los agentes se comuniquen entre sí. Por esta razón, solo cargaremos esta herramienta en los agentes que pueden comunicarse con otros, es decir, aquellos cuya lista de recipientAgents no esté vacía.

  private addCommonTools(agent: Agent) {
    const recipientAgents = this.getAgentCommunications(agent);
    if (recipientAgents.length > 0) {
      agent.addTool(
        new TalkToAgent({
          senderAgent: agent,
          agency: this,
        }),
      );
    }
  }

TalkToAgent

La clase TalkToAgent es una herramienta especializada diseñada para facilitar la comunicación directa y sincrónica entre agentes dentro de la agencia. Su objetivo principal es permitir que un agente envíe un mensaje directamente a otro agente específico y reciba una respuesta exclusiva de ese agente.

Al usar esta herramienta, un agente puede enviar un mensaje utilizando los siguientes parámetros:

recipient: Especifica el nombre del agente destinatario al que se enviará el mensaje.
message: Describe la tarea que el agente destinatario debe completar.

Creamos esta clase extendiendo de Tooly especificando su nombre, descripción y los parámetros que utiliza. También obligamos a que se envíe el agente que la está utilizando y la instancia de la agencia, ya que necesitaremos estos objetos en el run

export class TalkToAgent extends Tool {
  senderAgent: Agent;
  agency: Agency;
  constructor({ senderAgent, agency }: Props) {
    super({
      name: "TalkToAgent",
      description:
        "Utiliza esta herramienta para facilitar la comunicación directa y sincrónica entre agentes especializados dentro de la agencia. Cuando envíes un mensaje usando esta herramienta, recibirás una respuesta exclusivamente del agente destinatario designado. Para continuar el diálogo, invoca esta herramienta nuevamente con el agente destinatario deseado y tu mensaje de seguimiento. Recuerda, la comunicación aquí es sincrónica; el agente destinatario no realizará ninguna tarea después de la respuesta. Eres responsable de transmitir las respuestas del agente destinatario de vuelta al usuario, ya que el usuario no tiene acceso directo a estas respuestas. Sigue interactuando con la herramienta para una interacción continua hasta que la tarea esté completamente resuelta.",
      parameters: {
        type: "object",
        properties: {
          recipient: {
            type: "string",
            description:
              "Por favor, especifica el nombre del agente destinatario",
          },
          message: {
            type: "string",
            description:
              "Por favor, especifica la tarea que el agente destinatario debe completar. Concéntrate en aclarar en qué consiste la tarea, en lugar de proporcionar instrucciones exactas.",
          },
        },
        required: ["message"],
      },
    });
    this.senderAgent = senderAgent;
    this.agency = agency;
  }

  async run(parameters: RunProps): Promise<string> {
    const senderName = this.senderAgent.name;
    const recipientName = parameters.recipient;
    const message = parameters.message;
    const thread = this.agency.getThread(senderName, recipientName);
    if (!thread) return "ERROR: No puedes comunicarte con ese agente.";
    return await thread.send(message);
  }
}

En el constructor definimos la descripción de esta herramienta, para que OpenAI sepa como utilizarla y del mismo modo explicamos como funcionan los 2 parámetros que tiene. Por otro lado, en el run, lo que hacemos es utilizar el método getThread de la agencia para recuperar el hilo que conecta a los 2 agentes. Seguidamente agregamos un nuevo mensaje en él y devolvemos su respuesta.

Implementación de la app `back`

Vamos con la última parte del monorepo, la app back, que será la encargada de construir la agencia. Como ya hemos mencionado, este artículo trata de explicar las directrices para la construcción de las agencias, pero no de construir ninguna agencia en particular. En posteriores artículos crearemos ejemplos de agencias a partir de este marco de trabajo. En estos ejemplos será en esta parte back donde trabajaremos principalmente, definiendo agentes, herramientas, etc. A pesar de esto, sí que considero necesario finalizar el artículo viendo un ejemplo de como se puede utilizar todo lo mencionado. Por ello vamos a construir un "mini proyecto" que nos permita poner las cosas en funcionamiento.

Para ello, vamos a construir una agencia que ayude al usuario a resolver operaciones matemáticas básicas. En un caso real, nunca tendría sentido utilizar una agencia para esto; cualquier asistente por si solo haría a la perfección lo que vamos a plantear. Pero nos sirve para ilustrar como funciona la agencia.

Vamos a definir 2 agentes, uno principal (MainAgent) que interactuará con el usuario y otro secundario (MathAgent) que será al que se le delegarán los cálculos matemáticos que se necesiten hacer. Es decir, cuando MainAgent detecte que la conversación requiera de realizar una operación matemática, en lugar de realizarla por sí mismo, enviará un mensaje a MathAgent pidiéndole que realice dicha operación y MainAgent utilizará la respuesta que este le de para continuar su conversación.

MathAgent

Empezamos definiendo MathAgent

export class MathAgent extends Agent {
  constructor() {
    super({
      name: "MathAgent",
      description: path.resolve(__dirname, "./description.md"),
      instructions: path.resolve(__dirname, "./instructions.md"),
      tools: [new OperationTool()],
    });
  }
}

Como descripción le asignamos lo siguiente:

Eres un agente especializado en realizar operaciones matemáticas.

Y en cuanto a las instrucciones:

Responde al usuario de cualquier sobre cualquier operación matemática que te consulte. Apóyate en la herramienta con la que cuentas para realizar la operación.

Con este le hacemos saber al agente cual es su función, bastante simple en este caso. Ahora vamos con las tools, en concreto con la única que le hemos asignado, OperationTool

export class OperationTool extends Tool {
  constructor() {
    super({
      name: "OperationTool",
      description:
        "Utiliza esta herramienta para realizar operaciones matemáticas. Debes especificar el tipo de operación que deseas realizar y los dos números que deseas operar. Puedes elegir entre 'add', 'subtract', 'multiply' o 'divide'.",
      parameters: {
        type: "object",
        properties: {
          operation: {
            type: "string",
            enum: ["add", "subtract", "multiply", "divide"],
            description:
              "La operación que deseas realizar. Puede ser 'add' para sumar, 'subtract' para restar, 'multiply' para multiplicar o 'divide' para dividir",
          },
          number1: {
            type: "number",
            description:
              "El primer valor de la operación matemática que deseas realizar",
          },
          number2: {
            type: "number",
            description:
              "El segundo valor de la operación matemática que deseas realizar",
          },
        },
        required: ["operation", "number1", "number2"],
      },
    });
  }

  //----------- Run method ---------------------------

}

Como vemos, creamos una clase que extiende de Tool y en su definición especificamos lo que esta herramienta hace y los parámetros que ha de recibir cuando sea invocada. Así le contamos al agente como debe usar esta herramienta. Solo nos queda implementar el método run para llevar a cabo la ejecución de la misma.

  async run(parameters: OperationRunProps): Promise<string> {
    const { operation, number1, number2 } = parameters;
    try {
      switch (operation) {
        case "add":
          return `El resultado de sumar ${number1} y ${number2} es ${number1 + number2}`;
        case "subtract":
          return `El resultado de restar ${number1} y ${number2} es ${number1 - number2}`;
        case "multiply":
          return `El resultado de multiplicar ${number1} y ${number2} es ${number1 * number2}`;
        case "divide":
          return `El resultado de dividir ${number1} entre ${number2} es ${number1 / number2}`;
        default:
          return "Por favor, especifica una operación válida: 'add', 'subtract', 'multiply' o 'divide'";
      }
    } catch (e) {
      console.log("Error in OperationTool.run", e);
      return "No he podido realizar la operación. Por favor, comprueba que los valores que me has proporcionado son correctos y vuelve a intentarlo.";
    }
  }

En este método evaluamos que operación hay que realizar y cuales son sus parámetros. Con ello realizamos la operación y devolvemos al agente el mensaje oportuno. También manejamos el caso de que no recibamos una operación válida o se produzca cualquier excepción en el cálculo de la misma.

MainAgent

Pasamos ahora al agente principal, que es el responsable de comunicar con el usuario y de delegar al MathAgent cuando la conversación requiera realizar alguna operación matemática.

export class MainAgent extends Agent {
  constructor() {
    super({
      name: "MainAgent",
      description: path.resolve(__dirname, "./description.md"),
      instructions: path.resolve(__dirname, "./instructions.md"),
      tools: [],
    });
  }
}

Le damos la siguiente descripción:

Eres el agente principal de la agencia. Tu función es interactuar con el usuario de forma cordial y resolver las dudas que tenga sobre matemáticas hablando con el agente MathAgent.

Y las siguientes instrucciones:

## Instrucciones del Agente MainAgent

- Mantén una conversación natural con el usuario, respondiendo de forma cordial a las preguntas generales que te realice.

- Cuando necesites realizar una operación matemática para continuar con la conversación, **no la realices por ti mismo**. En cambio utiliza la herramienta `TalkToAgent` para trasladar esa operación al agente `MathAgent`. Utiliza la respuesta que te de este agente para continuar con la conversación.

Con esto tenemos listos los agentes y solo nos quedarían 2 cosas por hacer para poder lanzar nuestra agencia. Por un lado crear la carpeta db que usaremos para persistir los datos. Y por otro lado crear la propia agencia, para lo cual creamos una clase que extienda de Agency.

export class MathAgency extends Agency {
  mainAgent: MainAgent;
  mathAgent: MathAgent;

  constructor() {
    super({
      name: "Maths Agency",
    });
    this.mainAgent = new MainAgent();
    this.mathAgent = new MathAgent();
  }

  getAgents(): Agent[] {
    return [this.mainAgent, this.mathAgent];
  }

  getAgentCommunications(agent: User): Agent[] {
    switch (agent) {
      case this.user:
        return [this.mainAgent];
      case this.mainAgent:
        return [this.mathAgent];
      default:
        return [];
    }
  }

  getDBPath(): string {
    return path.resolve(__dirname, "./db");
  }
}

En este punto ya tenemos todo listo para poner en marcha nuestra agencia. Solo nos queda definir el fichero main.ts en el que inicializamos la agencia

const agency = new MathAgency();

const run = async () => {
  try {
    await agency.run();
    await agency.initApi(3001);
  } catch (err) {
    console.error(err);
  }
};
run();

Pruebas

Para finalizar vamos a ver a nuestra agencia en funcionamiento. Para ello tenemos que ponernos en la raíz del monorepo y ejecutar pnpm run dev, con lo que haremos que tanto la web como el back inicien en modo de desarrollo. Tras esto podemos abrir en el navegador la url http://localhost:3000 para cargar la web que nos permite interactuar con la agencia.

Vamos a hacer una primera prueba sencilla para ver que todo funciona. Abrimos la conversación con MainAgent y, tras un saludo, le decimos que nos diga cuanto es 5 por 3.

En la imagen podemos ver lo que ha sucedido. En cuanto el agente ha detectado que la conversación implica una operación matemática ha ejecutado la tool TalkToAgent para enviarle la pregunta a MathAgent. Si ahora abrimos la conversación entre MainAgent y MathAgentvemos como este último recibe la pregunta y, como implica una operación matemática, deduce que debe usar la tool Operation para resolver dicha operación. Seguidamente responde a MainAgent con la solución y este último, a partir de dicha respuesta, nos responde a nosotros.

Como podemos ver todo funciona según lo esperado. Tenemos 2 agentes que se pueden comunicar entre ellos y que pueden utilizar herramientas cuando consideren que es necesario.

Vamos con una segunda prueba un poco más interesante para ver el poder de esta tecnología. Vamos a borrar las conversaciones actuales y empezar una nueva. Para borrarlas tenemos que eliminar los ficheros de la carpeta /back/src/maths-agency/.db. (Sí, se que deberíamos de implementar un mejor mecanismo para limpiar la caché, por el momento tenemos que hacerlo así). A continuación vamos a iniciar una nueva conversación con MainAgent. En este caso le vamos proponer que nos resuelva un problema matemático.

Como podemos ver, en ningún momento le hemos dicho directamente que tiene que resolver una operación matemática. El agente deduce por sí mismo que para contestar a esa pregunta tiene que usar operaciones matemáticas por lo que la delega a MathAgent. Y este último deduce de la pregunta las operaciones debe de realizar y las delega a su tool Operation. Este funcionamiento es muy potente ya que, cuando lo llevemos a problemas complejos, nos da la posibilidad de crear agentes a los que solo debemos de decirle lo que pueden hacer y como han de hacerlo, pero dejando que ellos mismos decidan cuando han de realizar las acciones que consideren. Y como podemos ver es algo que son capaces de hacer muy bien.

Fin

En este artículo, hemos explorado y explicado una posible solución para la creación de agencias de IA utilizando TypeScript y un enfoque de monorepo que nos permite extender y utilizar este software de manera ágil y eficiente.

Aquí dejo el enlace al repositorio en GitHub donde está implementado este proyecto y todo lo comentado en el artículo. Decir que este repositorio cuenta con varias ramas:

La rama maths-agency contiene el código exacto que se presenta en este artículo. Mantendremos esta rama en su estado actual para que los lectores puedan ver la implementación tal como se explica en el artículo.
La rama base contiene los componentes principales del proyecto, como la interfaz web o el paquete agency. En el momento de redactar este artículo, las ramas maths-agency y base estarán totalmente alineadas. Sin embargo, a medida que se realicen mejoras en el marco de trabajo base, estas se irán incorporando a la rama base. La idea de esta rama es proporcionar un punto de partida para la creación de nuevas agencias.

Además de estas dos ramas, puede que haya otras que contendrán diferentes implementaciones de agencias y se corresponderán con artículos posteriores.

Espero que este artículo haya sido de su interés y te ayude a entender un poco mejor este concepto de agencias de IA. Como hemos mencionado el principio, la implementación aquí realizada es básica y no la aconsejo para llevar un proyecto a producción. Las librerías o frameworks que hemos mencionado al inicio del artículo implementan este concepto de una forma mucho más robusta y dotan de un montón de herramientas extra que nos permiten abordar problemas complejos de una forma mucho más sencilla. No reinventes la rueda (como he hecho yo) a no ser que sea por cuestiones de aprendizaje.

Por último, finalizar diciendo que, si alguien que esté probando este proyecto detecta algún tipo de problema o, si quiere realizar algún tipo de propuesta o idea basada en este concepto, solo tiene que contactarme y estoy más que abierto para ayudar o comentar lo que sea 😉

Construyendo un Monorepo en Typescript utilizando pnpm

Enol Casielles — Sun, 19 May 2024 05:01:34 +0000

En este artículo, explicaremos qué es un Monorepo, por qué es beneficioso utilizarlo en ciertos tipos de proyectos y cómo podemos construir uno utilizando pnpm

¿Qué es un monorepo?

Un monorepo, como su nombre indica, es un repositorio único que contiene múltiples paquetes o partes de un sistema. Pensemos, por ejemplo, en una arquitectura básica de un proyecto web. Podríamos tener, por un lado, un proyecto de frontend y, por otro, un proyecto de backend. Ambos serían totalmente independientes entre sí, contando con su propio repositorio, código fuente, dependencias, etc.

Por el contrario, cuando trabajamos con un monorepo, estos dos proyectos estarían bajo el mismo repositorio. Seguirían siendo totalmente independientes en términos de despliegue y ejecución, pero tendríamos la capacidad de compartir ciertos elementos entre ellos cuando sea necesario.

¿Cuando es interesante utilizarlos?

Para ilustrar esto mejor, imaginemos que en el ejemplo anterior tenemos que extenderlo y crear un tercer proyecto. Este proyecto será otro frontend que utilizará otro tipo de usuario, por ejemplo, un panel de administración. No sería de extrañar que este nuevo frontend comparta componentes de UI con el otro frontend, ¿verdad?

¿Cómo solucionamos esto cuando trabajamos en una arquitectura multirepo? Probablemente copiando estos componentes al nuevo proyecto, lo cual nos obliga a mantener componentes idénticos en dos lugares diferentes.

Tendría mucho más sentido que esos componentes estén en algún sitio donde ambos proyectos puedan utilizarlos, sin necesidad de duplicarlos. Algo como un paquete externo que ambos proyectos importen. Pues bien, un enfoque monorepo nos habilita el hacer esto de una forma sencilla y organizada.

Cuando estos dos proyectos viven bajo el mismo monorepo, podemos añadir un tercer proyecto (o paquete) que se encargue de implementar estos componentes comunes y que sea importado por ambos frontends.

Otro ejemplo

Otro ejemplo interesante es cuando queremos compartir clases o modelos entre el frontend y el backend. Frecuentemente, en el backend se definen clases con los modelos de respuesta que los diferentes endpoints devolverán y, a su vez, en el frontend defines también modelos para gestionar la respuesta.

Estas clases probablemente sean duplicadas en ambos proyectos, por lo que tendría mucho más sentido si se encuentran en un paquete independiente que ambos proyectos puedan importar. De nuevo, un caso que una arquitectura monorepo nos permite implementar y mantener de forma sencilla.

¿Cómo puedo construir un monorepo?

Vista la teoría y la justificación de por qué es interesante este enfoque, vamos a ver cómo podemos construir uno en TypeScript utilizando la herramienta pnpm, que es una alternativa a npm que, por su diseño y funcionamiento, encaja mucho mejor para la construcción de este tipo de arquitecturas.

Para empezar, nos ubicamos en la carpeta de trabajo y creamos un nuevo proyecto vacío utilizando pnpm.

pnpm init

Debes tener pnpm instalado en tu máquina. En su web oficial puedes ver como instalarlo

Esto nos creará el típico package.json en la carpeta. Hasta este punto, lo que tenemos es un proyecto de Node estándar gestionado por pnpm. Para convertirlo a un proyecto monorepo, tenemos que crear un archivo pnpm-workspace.yaml

packages:
  - "apps/*"
  - "packages/*"

Este archivo especifica en qué rutas estarán los distintos paquetes de nuestro monorepo. En este caso, definimos dos posibles carpetas, apps y packages, por lo que podemos aprovechar ya para crear estas dos carpetas en nuestro proyecto, que de momento las dejamos vacías.

Hacemos esta distinción de carpetas para diferenciar las aplicaciones de los paquetes que van a ser utilizados por estas aplicaciones. Esto no es obligatorio; para el monorepo no hay distinción alguna entre lo que es una app y lo que es un paquete. La hacemos nosotros por la diferencia conceptual de lo que representan. A partir de ahora, cuando hablemos de un paquete, será aplicable a cualquiera de los dos tipos, ya que realmente, es así en la terminología utilizada en un monorepo con pnpm

Como ya hemos comentado, cada uno de los paquetes será una entidad independiente, nuevos proyectos pnpm que contarán con su package.json, con su listado de dependencias, scripts personalizados, etc. Pero lo importante es que al estar en el monorepo, será este quien se encargue de gestionar las dependencias de cada uno de ellos. Esto quiere decir que, cuando instalamos una dependencia en alguno de los paquetes, será el monorepo quien la instalará y quien decidirá que el alcance de dicha dependencia es para dicho paquete y no para el resto. Ahora bien, ¿qué pasa si instalamos una dependencia en el paquete raíz? Recordemos que el paquete raíz no deja de ser un proyecto pnpm también, por lo que se puede instalar algo a este nivel. Pues bien, lo que pasará es que dicha dependencia estará disponible en todos los paquetes.

Por lo general, no querremos instalar dependencias en raíz, pero sí es habitual hacer alguna excepción. Por ejemplo, algo que suelo hacer es instalar TypeScript y configurar eslint a este nivel de raíz. La razón de hacer esto es que sé seguro que todos los paquetes se van a escribir en TypeScript y quiero unificar las reglas de escritura de código en todos ellos. Pero esto no tiene por qué ser así; es una decisión totalmente de la cultura de ingeniería del proyecto.

Instalando dependencias globales

Dicho lo anterior, vamos a configurar estas dependencias visibles para todos los paquetes. Para ello, simplemente nos ubicamos en la raíz del proyecto y ejecutamos:

pnpm install typescript eslint -w

Es importante destacar el uso de la flag -w. Cuando tratas de instalar algo en la raíz del monorepo, por defecto pnpm te lanza una advertencia para que tengas en cuenta que estás en raíz. Como no es lo habitual instalar dependencias a este nivel, pnpm considera que puede ser un error y te advierte. Con la flag -w indicas que eres consciente de ello y que quieres instalarlo en raíz, evitando que te salte el aviso. Este comportamiento también puede ser evitado estableciendo un ajuste en el proyecto, lo veremos más adelante.

Una vez hecho esto, ya podemos instalar estas dos dependencias y ver como aparecen en el package.json de raíz. Vamos a proceder ahora a configurar eslint, para ello vamos a utilizar el configurador que la propia dependencia nos ofrece. Pero antes de hacer esto es importante que tengamos en cuenta algo. Como decíamos antes, pnpm bloquea las instalaciones a nivel raíz si no llevan la flag -w. El configurador de eslint, a pesar de que sí permite la instalación usando pnpm, no utilizará esta flag -w, por lo que no podrá finalizar correctamente. ¿Cómo podemos solucionar esto? Estableciendo un ajuste a nivel proyecto que le indique a pnpm que ignore esta advertencia. Esto se hace creando un archivo .npmrc e insertando la siguiente línea:

ignore-workspace-root-check=true

Con esto, la advertencia será ignorada y se podrá instalar en raíz sin la flag -w. Procedemos entonces a la configuración del eslint:

pnpm eslint --init

El resultado de este configurador será la instalación de las dependencias necesarias y la creación del fichero .eslintrc.json en la raíz del proyecto:

{
    "env": {
        "browser": true,
        "es2021": true,
        "node": true
    },
    "extends": "standard-with-typescript",
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "rules": {
    }
}

En este punto, tenemos todo listo para empezar a crear paquetes en el monorepo 🚀

Definiendo el proyecto

Antes de empezar con la implementación de los diferentes paquetes, vamos a explicar brevemente el proyecto que, a modo de ejemplo, vamos a abordar. Será algo muy sencillo ya que queremos centrarnos en cómo funciona el monorepo y no en la aplicación en sí misma. Por esa razón, no voy a entrar en detalle en nada referente a la implementación de la aplicación. Solo mencionar que será la típica App de lista de tareas, con un frontend hecho con React + Vite y una API hecha con Express, ambos proyectos en TypeScript.

Además, para ilustrar mejor como usar un monorepo, crearemos un paquete llamado core que será consumido por ambas apps y que definirá clases o tipos que ambos puedan necesitar.

En el enlace al repo que dejo al final del artículo, podéis ver la implementación completa de cada parte

Creando el primer paquete

Vamos a empezar con la creación de la app para el frontend. Nos vamos a la carpeta apps y creamos un proyecto en React usando Vite:

pnpm create vite@latest front -- --template react-ts

Seguimos las instrucciones del configurador para crear el proyecto React con TypeScript e instalar todos los paquetes necesarios. Si tras instalarlo, nos vamos a apps/front y hacemos pnpm run dev, deberíamos poder lanzar correctamente el proyecto React en ejecución. Vamos a hacer ahora algunas modificaciones para adaptarlo mejor al monorepo.

Antes que nada, vamos a decirle a Vite que utilice el puerto 3000 para nuestro frontend, en lugar de uno aleatorio como hace por defecto. Nos vamos al vite.config.ts y agregamos el siguiente objeto server:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
  }
})

A continuación, vamos a adaptar el proyecto un poco mejor para vivir en el monorepo. La instalación por defecto de Vite configurará su propio TypeScript y eslint, pero como hemos comentado, nosotros queremos usar el del monorepo. Por tanto, lo que haremos es desinstalar localmente estas dependencias y eliminar todos los archivos. Nos vamos al package.json y eliminamos las siguientes dependencias:

typescript
eslint
@typescript-eslint/eslint-plugin
@typescript-eslint/parser

En el momento de escribir este artículo, estas eran las dependencias relacionadas con TypeScript o eslint que Vite instalaba por defecto. Puede que en tu caso esto cambie un poco según la versión de Vite utilizada. Asegúrate de eliminar todas aquellas que tengan que ver con estas herramientas.

Una vez eliminadas en el package.json, ejecutamos pnpm install en apps/front para que la desinstalación se lleve a cabo. Por último, eliminamos el archivo .eslintrc para que no utilice la configuración de eslint que ahí se indica. Tras hacer esto, nuestro proyecto frontend ya debería usar las reglas de eslint definidas en raíz.

Ahora bien, es cierto que, según el tipo de proyecto TypeScript en el que estemos, quizá nos interese tener alguna configuración diferente. Por ejemplo, este paquete frontend es una aplicación con React y, en este caso, es muy común instalar el plugin de eslint para React eslint-plugin-react. No tiene sentido que instalemos este plugin en raíz y que nuestro proyecto api también esté expuesto a lo que dicte este plugin. Por tanto, vamos a ver cómo se puede adaptar la configuración de eslint para cada proyecto.

Primero, instalamos a este nivel front el paquete con el plugin mencionado.

cd apps/front
pnpm install -D eslint-plugin-react

Luego creamos otro fichero .eslintrc.json a nivel front y agregamos lo siguiente:

{
  "extends": [
    "../../.eslintrc", 
    "plugin:react/recommended"
  ],
  "plugins": [
      "react"
  ],
  "rules": {}
}

Así le estamos indicando lo siguiente: por un lado, que utilice dicho plugin para React; por otro lado, que extienda la configuración que tenemos definida en raíz; y por último, que extienda también lo que nos define el propio plugin. Finalmente, al igual que hemos hecho en raíz, definimos unas reglas personalizadas, por el momento vacías.

Si utilizas VSCode y la extensión para eslint, en este momento deberían aparecer errores en tus archivos. Por ejemplo, podemos abrir el App.tsx y ver cómo hay varios errores de sintaxis. Esto se debe a que ahora la configuración de eslint es la que viene de Standard, la guía de estilos que decidimos elegir cuando configuramos eslint en raíz, extendida además por la del plugin de React que le acabamos de añadir. Entonces, tenemos que adaptar nuestro código para cumplir con esto. Tenemos dos opciones para abordarlo: arreglar los errores que nos indica o modificar las reglas definidas. Esto, de nuevo, es una decisión que has de tomar según cómo quieras afrontar tu desarrollo.

En mi caso, lo que haré será una mezcla de ambas opciones. Añadiré las siguientes tres reglas a la configuración de eslint en raíz:

{
  //...
  "rules": {
    "@typescript-eslint/explicit-function-return-type": "off",
    "@typescript-eslint/no-floating-promises": "off",
    "@typescript-eslint/no-misused-promises": "off"
  }
}

Y añadiré la siguiente a la configuración del proyecto front:

{
  //...
  "rules": {
    "react/react-in-jsx-scope": "off"
  }
}

Una vez hecho esto, corregiré el resto de errores o advertencias que eslint me indique.

En este punto, ya tenemos todo listo para crear nuestra App. Como decía anteriormente, no vamos a entrar en detalles de la implementación. Puedes ir al repo y ver cómo está hecho.

Creando otro paquete para la Api

Ahora que ya hemos visto cómo crear y adaptar un proyecto al monorepo, vamos a hacer lo mismo para la API. Como habíamos dicho, implementaremos una API usando Express.

Nos vamos a la carpeta apps y creamos un nuevo directorio llamada api. En este caso no usaremos ningún generador. Entramos en la carpeta api y creamos un nuevo proyecto pnpm vacío.

cd apps
mkdir api && cd api && pnpm init

Instalamos las dependencias necesarias

pnpm add express
pnpm add -D @types/express @types/node nodemon ts-node

Básicamente, lo que estamos haciendo es instalar Express y como dependencias de desarrollo:

Los tipos de Express y Node
Nodemon, que es una herramienta que nos permite recargar el servidor al guardar cambios en los archivos
ts-node, que nos permite ejecutar directamente código Typescript

Agregamos un fichero nodemon.json en raíz para especificar como debe funcionar esta herramienta.

{
  "watch": ["src"],
  "ext": "ts",
  "exec": "ts-node ./src/index.ts"
}

Así le estamos indicando es que debe escuchar a los archivos en la carpeta src con extensión .ts para que, cada vez que se guarde uno de ellos, ejecute ts-node en el archivo principal. Con eso, conseguimos ejecutar directamente la API con Typescript (ts-node se encarga por debajo de todo) y hacer que se recargue con cada cambio (nodemon se encarga)

Agregamos también el fichero tsconfig.json para indicar como se ha de realizar el transpilado a Javascript, así como algunas reglas de linting.

{
  "compilerOptions": {

    "module": "commonjs",
    "target": "ES2020",
    "outDir": "./dist",
    "incremental": true,
    "allowSyntheticDefaultImports": true,

    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

  }
}

Por último creamos los scripts en el package.json para realizar el dev, el build y el start.

{
  // ---
  "scripts": {
    //---
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "nodemon"
  },
}

Creando un paquete compartido

Lo siguiente que vamos a hacer es crear el paquete core, en el que implementaremos aquellas cosas que puedan ser comunes en ambas aplicaciones frontend y API. Creamos una nueva carpeta en packages llamada core y, estando en ella, creamos de nuevo un proyecto pnpm básico.

cd packages
mkdir core
cd core
pnpm init

A continuación creamos el tsconfig.json para especificar a Typescript como ha de realizar el compilado a Javascript.

{
  "compilerOptions": {

    "module": "ESNext",
    "target": "ES2015",
    "outDir": "./dist",
    "incremental": true,
    "allowSyntheticDefaultImports": true,
    "isolatedModules": true,

    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "removeComments": true,

    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

  }
}

Esta configuración es similar a la del proyecto API. En este caso, como sistema de módulos, usamos ESNext que lo hará más compatible para ser importado por las diferentes apps. Además, agregamos algunas propiedades que permiten generar las declaraciones de tipos y los archivos de mapas entre el código fuente y el código compilado. Esto es interesante ya que ayuda al IDE a entender la estructura del paquete y facilita cosas como ir a la definición de aquello que el paquete exporte cuando lo estamos usando en otro paquete

Creamos también un nodemon.json para poder realizar el compilado en modo desarrollo:

{
  "watch": ["src"],
  "ext": "ts",
  "exec": "npm run build"
}

Y finalmente, agregamos los scripts para hacer el build y el dev en el package.json

{
  // ---
  "scripts": {
    //---
    "build": "tsc -p tsconfig.json",
    "dev": "nodemon"
  },
}

Y con esto ya tenemos también listo este paquete para escribir el código que necesitemos.

Importando el paquete

Lo único que tenemos que hacer ahora es importar el paquete core en las apps. Esto lo hacemos como cualquier otro paquete, nos vamos al directorio de cada una de las apps y hacemos:

pnpm add core@workspace:^

De esta forma, indicamos que instale un paquete llamado core que se encuentra en el workspace, para que lo busque directamente del monorepo y no en repositorios externos.

Una vez hecho esto, ya podremos utilizar en nuestras apps aquellos componentes que core exporte.

Scripts en paralelo

Para ir finalizando este artículo, vamos a ver una característica interesante de los monorepos que aún no hemos comentado: la posibilidad de ejecutar todos los scripts a la vez y en paralelo. Si nos fijamos, los tres paquetes tienen un script dev. Es muy posible que cuando estemos desarrollando, queramos tener levantados estos entornos de desarrollo en los tres paquetes. Pnpm nos permite hacer esto de una forma muy sencilla. Simplemente tenemos que ir al package.json de raíz y definir ahí el siguiente script dev:

{
  // ---
  "scripts": {
    //---
    "dev": "pnpm run --parallel dev",
  },
}

Esto busca todos los scripts dev que haya en cada uno de los paquetes que conforman el monorepo y los ejecuta en paralelo.

Otra cosa interesante que nos ofrece pnpm es la posibilidad de filtrar un script a solo ciertos paquetes. Esto se hace utilizando la flag --filter. Esto nos permite crear scripts con las operaciones más habituales de desarrollo que podamos necesitar. Por ejemplo, podríamos configurar para levantar cada una de las apps por separado o las dos a la vez pero sin el paquete core.

{ 
  // ---
  "scripts": {
    //---
    "dev": "pnpm run --parallel dev",
    "dev:front": "pnpm run --filter front dev",
    "dev:api": "pnpm run --filter api dev",
    "dev:apps": "pnpm run --filter api --filter front dev"
  },
}

Fin

Espero que este artículo sirva como una introducción para empezar a trabajar con monorepos en TypeScript usando pnpm. He tratado de realizar paso a paso la configuración que suelo utilizar para trabajar con este tipo de arquitecturas en proyectos TypeScript. Creo que puede servir como una buena base con la que empezar a construir proyectos usando este enfoque.

En posteriores artículos del blog, utilizaremos esto como base para crear ciertos proyectos y/o explicar algunas técnicas de desarrollo que suelo utilizar en mi día a día.

Por último, dejo por aquí el link al repositorio en github en el que está implementado todo lo que hemos ido haciendo en este artículo.

DEV Community: Enol Casielles

Cómo Desarrollé MemoMate: Un Asistente Personal en Telegram con IA

Introducción

¿Qué es MemoMate?

Gestión de Contactos

Información sobre Contactos

Recordatorios

Free vs Premium

Plataforma Web

Arquitectura y Tecnologías

Tecnologías empleadas

El Proceso de Desarrollo

Definición del Proyecto

Estructura Base

Sistema de Autenticación

Integración con OpenAI

Agent

Tool

Thread

Embeddings

Implementación del Asistente

Conectar Bot con Asistente. Clase MemoMateProcessor

Crons para recordatorios

Pinecone para la búsqueda de contactos

Web en Next

Suscripciones con Stripe

Interfaz de Suscripción

Integración con el Bot

Webhooks de Stripe

Mejoras Futuras y Conclusión

Cómo uso Cursor para ser más productivo en desarrollo web

La importancia de una buena documentación

Creación de la documentación con ChatGPT

Partir de un proyecto base

Usar .cursorrules

Empezando a trabajar

Creando un nuevo módulo

Agregando funcionalidad a un módulo

Requerimientos diversos

Chat VS Composer

Modelos a utilizar

Actualización continua de la documentación

Herramienta Git Diff de Cursor

Un cambio a la vez

¿Qué pasa con la UI?

Documento de material gráfico

Capturas de pantalla

Propiedades como contexto

Fin

Arquitectura Hexagonal con Typescript y pnpm

¿Por qué una arquitectura hexagonal?

Ventajas clave de la arquitectura hexagonal:

Monorepo y Arquitectura Hexagonal: Un enfoque eficiente

Proyecto de ejemplo

Implementación

Domain

Application

Database

Aplicaciones api y web

API (NestJS)

Web (NextJS)

Inyección de dependencias con DI

Conclusión

Marco de Trabajo para la Creación de Agencias de Inteligencia Artificial

Motivación del proyecto

Concepto de Agencia de IA

Agente (Agent)

Misión

Herramienta (Tool)

Hilo (Thread)

Herramienta TalkToAgent

Usuario

Requisitos del Proyecto

Arquitectura del Marco de Trabajo

Monorepo con Typescript y pnpm

Python o Typescript

Interfaz de Usuario con Next.js

Paquete agency

Implementación de la Agencia

Implementación de la app web

Paquete `agency`

Implementación de la app `web`

Implementación del paquete `agency`

Implementación de la app `back`