efarmz-slackbot-data 1.0.0

package/src/application/agent/AgentLoop.test.ts

@@ -0,0 +1,275 @@
+import { describe, it, expect } from "vitest";
+import AgentLoop from "../agent/AgentLoop.js";
+import type LLMProvider from "@/domain/ports/LLMProvider.js";
+import type SqlValidator from "@/domain/ports/SqlValidator.js";
+import type SqlExecutor from "@/domain/ports/SqlExecutor.js";
+import type SchemaCatalog from "@/domain/ports/SchemaCatalog.js";
+import type { LLMRequest, LLMResponse } from "@/domain/ports/LLMProvider.js";
+import type SqlQuery from "@/domain/value-objects/SqlQuery.js";
+import type { QueryResult } from "@/domain/value-objects/QueryResult.js";
+import Conversation from "@/domain/entities/Conversation.js";
+import ConversationMessage from "@/domain/entities/ConversationMessage.js";
+import ThreadId from "@/domain/value-objects/ThreadId.js";
+import Question from "@/domain/value-objects/Question.js";
+import AgentLoopExceededError from "@/domain/errors/AgentLoopExceededError.js";
+import InvalidSqlError from "@/domain/errors/InvalidSqlError.js";
+
+class FakeLLMProvider implements LLMProvider {
+  private responses: LLMResponse[] = [];
+  private callCount = 0;
+
+  addResponse(response: LLMResponse): this {
+    this.responses.push(response);
+    return this;
+  }
+
+  async generate(_request: LLMRequest): Promise<LLMResponse> {
+    const response = this.responses[this.callCount];
+    if (!response) {
+      throw new Error(`No more responses configured for FakeLLMProvider (called ${this.callCount + 1} times)`);
+    }
+    this.callCount += 1;
+    return response;
+  }
+
+  getCallCount(): number {
+    return this.callCount;
+  }
+}
+
+class FakeSqlValidator implements SqlValidator {
+  private shouldFail = false;
+
+  failValidation(): this {
+    this.shouldFail = true;
+    return this;
+  }
+
+  validate(raw: string): string {
+    if (this.shouldFail) {
+      throw new InvalidSqlError(raw, `Validation failed`);
+    }
+    return raw;
+  }
+}
+
+class FakeSqlExecutor implements SqlExecutor {
+  private shouldFail = false;
+  private failureMessage = `Execution error`;
+
+  failExecution(message: string): this {
+    this.shouldFail = true;
+    this.failureMessage = message;
+    return this;
+  }
+
+  async execute(_query: SqlQuery): Promise<QueryResult> {
+    if (this.shouldFail) {
+      throw new Error(this.failureMessage);
+    }
+    return {
+      columns: [`result`],
+      rows: [{ result: `test_value` }],
+      rowCount: 1,
+    };
+  }
+}
+
+class FakeSchemaCatalog implements SchemaCatalog {
+  getDocumentation(): string {
+    return `Schema: test_table\n- id: integer\n- name: text`;
+  }
+}
+
+describe(`AgentLoop`, () => {
+  it(`should return finalText on immediate end_turn`, async () => {
+    const llm = new FakeLLMProvider().addResponse({
+      content: `The answer is 42`,
+      toolUses: [],
+      stopReason: `end_turn`,
+      inputTokens: 100,
+      outputTokens: 50,
+    });
+
+    const agent = new AgentLoop(llm, new FakeSqlValidator(), new FakeSqlExecutor(), new FakeSchemaCatalog(), 5);
+
+    const result = await agent.run({
+      conversation: null,
+      question: Question.create(`What is the answer?`),
+    });
+
+    expect(result.finalText).toBe(`The answer is 42`);
+    expect(result.executedSqls).toHaveLength(0);
+    expect(result.queryResult).toBeNull();
+    expect(result.inputTokens).toBe(100);
+    expect(result.outputTokens).toBe(50);
+    expect(llm.getCallCount()).toBe(1);
+  });
+
+  it(`should execute SQL and continue to end_turn`, async () => {
+    const llm = new FakeLLMProvider()
+      .addResponse({
+        content: ``,
+        toolUses: [
+          {
+            id: `tool_1`,
+            name: `run_sql`,
+            input: { sql: `SELECT 1 as num` },
+          },
+        ],
+        stopReason: `tool_use`,
+        inputTokens: 100,
+        outputTokens: 50,
+      })
+      .addResponse({
+        content: `The result is 1`,
+        toolUses: [],
+        stopReason: `end_turn`,
+        inputTokens: 150,
+        outputTokens: 60,
+      });
+
+    const agent = new AgentLoop(llm, new FakeSqlValidator(), new FakeSqlExecutor(), new FakeSchemaCatalog(), 5);
+
+    const result = await agent.run({
+      conversation: null,
+      question: Question.create(`Count something`),
+    });
+
+    expect(result.finalText).toBe(`The result is 1`);
+    expect(result.executedSqls).toHaveLength(1);
+    expect(result.executedSqls[0]).toBe(`SELECT 1 as num`);
+    expect(result.queryResult).toEqual({
+      columns: [`result`],
+      rows: [{ result: `test_value` }],
+      rowCount: 1,
+    });
+    expect(result.inputTokens).toBe(250);
+    expect(result.outputTokens).toBe(110);
+  });
+
+  it(`should handle SQL validation errors without throwing`, async () => {
+    const validator = new FakeSqlValidator().failValidation();
+    const executor = new FakeSqlExecutor();
+
+    const llm = new FakeLLMProvider()
+      .addResponse({
+        content: ``,
+        toolUses: [
+          {
+            id: `tool_1`,
+            name: `run_sql`,
+            input: { sql: `DROP TABLE users` },
+          },
+        ],
+        stopReason: `tool_use`,
+        inputTokens: 100,
+        outputTokens: 50,
+      })
+      .addResponse({
+        content: `The query was invalid`,
+        toolUses: [],
+        stopReason: `end_turn`,
+        inputTokens: 150,
+        outputTokens: 60,
+      });
+
+    const agent = new AgentLoop(llm, validator, executor, new FakeSchemaCatalog(), 5);
+
+    const result = await agent.run({
+      conversation: null,
+      question: Question.create(`Do something bad`),
+    });
+
+    expect(result.finalText).toBe(`The query was invalid`);
+    expect(result.executedSqls).toHaveLength(0);
+    expect(llm.getCallCount()).toBe(2);
+  });
+
+  it(`should handle SQL execution errors without throwing`, async () => {
+    const executor = new FakeSqlExecutor().failExecution(`Connection timeout`);
+
+    const llm = new FakeLLMProvider()
+      .addResponse({
+        content: ``,
+        toolUses: [
+          {
+            id: `tool_1`,
+            name: `run_sql`,
+            input: { sql: `SELECT * FROM nonexistent` },
+          },
+        ],
+        stopReason: `tool_use`,
+        inputTokens: 100,
+        outputTokens: 50,
+      })
+      .addResponse({
+        content: `Query failed, trying another approach`,
+        toolUses: [],
+        stopReason: `end_turn`,
+        inputTokens: 150,
+        outputTokens: 60,
+      });
+
+    const agent = new AgentLoop(llm, new FakeSqlValidator(), executor, new FakeSchemaCatalog(), 5);
+
+    const result = await agent.run({
+      conversation: null,
+      question: Question.create(`Get data`),
+    });
+
+    expect(result.finalText).toBe(`Query failed, trying another approach`);
+    expect(result.executedSqls).toHaveLength(0);
+    expect(result.queryResult).toBeNull();
+  });
+
+  it(`should throw AgentLoopExceededError when max turns reached`, async () => {
+    const llm = new FakeLLMProvider().addResponse({
+      content: ``,
+      toolUses: [
+        {
+          id: `tool_1`,
+          name: `run_sql`,
+          input: { sql: `SELECT 1` },
+        },
+      ],
+      stopReason: `tool_use`,
+      inputTokens: 100,
+      outputTokens: 50,
+    });
+
+    const agent = new AgentLoop(llm, new FakeSqlValidator(), new FakeSqlExecutor(), new FakeSchemaCatalog(), 1);
+
+    await expect(
+      agent.run({
+        conversation: null,
+        question: Question.create(`Query`),
+      }),
+    ).rejects.toThrow(AgentLoopExceededError);
+  });
+
+  it(`should restore conversation history on run`, async () => {
+    const llm = new FakeLLMProvider().addResponse({
+      content: `Continuing from history`,
+      toolUses: [],
+      stopReason: `end_turn`,
+      inputTokens: 100,
+      outputTokens: 50,
+    });
+
+    const threadId = ThreadId.create(`C123456789`, `1234567890.123456`);
+    let conversation = Conversation.create(threadId);
+    conversation = conversation.append(ConversationMessage.create(`user`, `First question`));
+    conversation = conversation.append(ConversationMessage.create(`assistant`, `First answer`));
+
+    const agent = new AgentLoop(llm, new FakeSqlValidator(), new FakeSqlExecutor(), new FakeSchemaCatalog(), 5);
+
+    const result = await agent.run({
+      conversation,
+      question: Question.create(`Follow-up question`),
+    });
+
+    expect(result.finalText).toBe(`Continuing from history`);
+    expect(llm.getCallCount()).toBe(1);
+  });
+});

package/src/application/agent/AgentLoop.ts

@@ -0,0 +1,101 @@
+import type LLMProvider from "@/domain/ports/LLMProvider.js";
+import type SqlValidator from "@/domain/ports/SqlValidator.js";
+import type SqlExecutor from "@/domain/ports/SqlExecutor.js";
+import type SchemaCatalog from "@/domain/ports/SchemaCatalog.js";
+import type Conversation from "@/domain/entities/Conversation.js";
+import type Question from "@/domain/value-objects/Question.js";
+import AgentLoopExceededError from "@/domain/errors/AgentLoopExceededError.js";
+import SqlQuery from "@/domain/value-objects/SqlQuery.js";
+import AgentContext from "./AgentContext.js";
+import type AgentRunResult from "./AgentRunResult.js";
+import type LLMMessage from "./LLMMessage.js";
+import RunSqlTool from "./tools/RunSqlTool.js";
+import type { RunSqlInput } from "./tools/RunSqlTool.js";
+
+class AgentLoop {
+  constructor(
+    private readonly llmProvider: LLMProvider,
+    private readonly sqlValidator: SqlValidator,
+    private readonly sqlExecutor: SqlExecutor,
+    private readonly schemaCatalog: SchemaCatalog,
+    private readonly maxTurns: number,
+  ) {}
+
+  async run(params: {
+    conversation: Conversation | null;
+    question: Question;
+  }): Promise<AgentRunResult> {
+    const context = AgentContext.init(params.conversation, params.question);
+    const systemPrompt = this.buildSystemPrompt();
+
+    for (let turn = 0; turn < this.maxTurns; turn++) {
+      const response = await this.llmProvider.generate({
+        systemPrompt,
+        messages: this.transformMessages(context.messages),
+        tools: [RunSqlTool.definition],
+      });
+
+      context.appendAssistantMessage(response.content, response.inputTokens, response.outputTokens);
+
+      if (response.stopReason === `end_turn`) {
+        return {
+          finalText: response.content,
+          executedSqls: context.executedSqls,
+          queryResult: context.lastQueryResult,
+          inputTokens: context.totalInputTokens,
+          outputTokens: context.totalOutputTokens,
+        };
+      }
+
+      for (const toolUse of response.toolUses) {
+        if (toolUse.name === `run_sql`) {
+          await this.handleRunSql(context, toolUse.id, toolUse.input as RunSqlInput);
+        }
+      }
+    }
+
+    throw new AgentLoopExceededError(this.maxTurns);
+  }
+
+  private async handleRunSql(
+    context: AgentContext,
+    toolUseId: string,
+    input: RunSqlInput,
+  ): Promise<void> {
+    try {
+      const query = SqlQuery.create(input.sql, this.sqlValidator);
+      const result = await this.sqlExecutor.execute(query);
+      context.recordSql(input.sql, result);
+      context.appendToolResult(toolUseId, JSON.stringify(result), false);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      context.appendToolResult(toolUseId, errorMessage, true);
+    }
+  }
+
+  private transformMessages(
+    messages: readonly LLMMessage[],
+  ): Array<{ role: "user" | "assistant"; content: string }> {
+    return messages.map((msg) => ({
+      role: msg.role,
+      content: typeof msg.content === `string` ? msg.content : JSON.stringify(msg.content),
+    }));
+  }
+
+  private buildSystemPrompt(): string {
+    const schemas = this.schemaCatalog.getDocumentation();
+    return `You are an SQL expert assistant for efarmz analytics.
+
+${schemas}
+
+Instructions:
+- You can execute read-only SQL SELECT queries to answer user questions
+- You MUST always think step-by-step before writing SQL
+- Use the available schema information to construct valid queries
+- Ensure queries are efficient and respect the limits (max 1000 rows, 30s timeout)
+- If a query fails, analyze the error and try a different approach
+- Provide clear explanations of what the data shows`;
+  }
+}
+
+export default AgentLoop;

package/src/application/agent/AgentRunResult.ts

@@ -0,0 +1,11 @@
+import QueryResult from "@/domain/value-objects/QueryResult";
+
+type AgentRunResult = {
+  readonly finalText: string;
+  readonly executedSqls: readonly string[];
+  readonly queryResult: QueryResult | null;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+};
+
+export default AgentRunResult;

package/src/application/agent/LLMMessage.ts

@@ -0,0 +1,16 @@
+type LLMMessageRole = `user` | `assistant`;
+
+type LLMToolResultContent = {
+  readonly type: `tool_result`;
+  readonly toolUseId: string;
+  readonly content: string;
+  readonly isError: boolean;
+};
+
+type LLMMessage = {
+  readonly role: LLMMessageRole;
+  readonly content: string | LLMToolResultContent;
+};
+
+export default LLMMessage;
+export type { LLMMessageRole, LLMToolResultContent };

package/src/application/agent/tools/RunSqlTool.ts

@@ -0,0 +1,23 @@
+const RunSqlTool = {
+  definition: {
+    name: `run_sql`,
+    description: `Execute a read-only SQL SELECT query on the efarmz PostgreSQL databases. The query must start with SELECT or WITH and cannot contain INSERT, UPDATE, DELETE, DROP, or other mutation keywords. Results are limited to 1000 rows.`,
+    inputSchema: {
+      type: `object`,
+      properties: {
+        sql: {
+          type: `string`,
+          description: `The SQL SELECT query to execute. Must be a valid PostgreSQL query.`,
+        },
+      },
+      required: [`sql`],
+    },
+  },
+} as const;
+
+type RunSqlInput = {
+  sql: string;
+};
+
+export default RunSqlTool;
+export type { RunSqlInput };

package/src/application/formatting/CsvRenderer.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from "vitest";
+import CsvRenderer from "../formatting/CsvRenderer";
+import QueryResult from "@/domain/value-objects/QueryResult";
+
+describe(`CsvRenderer`, () => {
+  it(`renders simple data as CSV`, () => {
+    const result = QueryResult.create(
+      [`name`, `age`],
+      [
+        { name: `Alice`, age: 30 },
+        { name: `Bob`, age: 25 },
+      ]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`name,age\nAlice,30\nBob,25`);
+  });
+
+  it(`escapes values containing comma`, () => {
+    const result = QueryResult.create(
+      [`name`, `city`],
+      [{ name: `Smith, John`, city: `New York` }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`name,city\n"Smith, John",New York`);
+  });
+
+  it(`escapes double quotes by doubling them`, () => {
+    const result = QueryResult.create(
+      [`text`],
+      [{ text: `He said "hello"` }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`text\n"He said ""hello"""`);
+  });
+
+  it(`handles null values as empty strings`, () => {
+    const result = QueryResult.create(
+      [`name`, `age`],
+      [
+        { name: `Alice`, age: null },
+        { name: null, age: 30 },
+      ]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`name,age\nAlice,\n,30`);
+  });
+
+  it(`handles undefined values as empty strings`, () => {
+    const result = QueryResult.create(
+      [`name`, `age`],
+      [{ name: `Alice`, age: undefined }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`name,age\nAlice,`);
+  });
+
+  it(`encodes output as UTF-8 with accented characters`, () => {
+    const result = QueryResult.create(
+      [`nom`, `email`],
+      [
+        { nom: `François`, email: `françois@example.fr` },
+        { nom: `José`, email: `josé@example.es` },
+      ]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(
+      `nom,email\nFrançois,françois@example.fr\nJosé,josé@example.es`
+    );
+  });
+
+  it(`escapes values containing newlines`, () => {
+    const result = QueryResult.create(
+      [`text`],
+      [{ text: `Line 1\nLine 2` }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`text\n"Line 1\nLine 2"`);
+  });
+
+  it(`escapes values containing carriage returns`, () => {
+    const result = QueryResult.create(
+      [`text`],
+      [{ text: `Line 1\rLine 2` }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`text\n"Line 1\rLine 2"`);
+  });
+
+  it(`handles complex escaping with multiple special characters`, () => {
+    const result = QueryResult.create(
+      [`data`],
+      [{ data: `"Value", with, "quotes" and, commas` }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(
+      `data\n"""Value"", with, ""quotes"" and, commas"`
+    );
+  });
+
+  it(`returns valid UTF-8 buffer`, () => {
+    const result = QueryResult.create(
+      [`name`],
+      [{ name: `Test` }]
+    );
+
+    const buffer = CsvRenderer.render(result);
+
+    expect(buffer).toBeInstanceOf(Buffer);
+    expect(buffer.toString(`utf-8`)).toBe(`name\nTest`);
+  });
+
+  it(`handles empty rows array`, () => {
+    const result = QueryResult.create([`name`, `age`], []);
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`name,age`);
+  });
+
+  it(`handles zero and false values correctly`, () => {
+    const result = QueryResult.create(
+      [`count`, `active`],
+      [
+        { count: 0, active: false },
+        { count: 100, active: true },
+      ]
+    );
+
+    const buffer = CsvRenderer.render(result);
+    const csv = buffer.toString(`utf-8`);
+
+    expect(csv).toBe(`count,active\n0,false\n100,true`);
+  });
+});

package/src/application/formatting/CsvRenderer.ts

@@ -0,0 +1,34 @@
+import type { QueryResult } from "@/domain/value-objects/QueryResult";
+
+const escape = (value: unknown): string => {
+  if (value === null || value === undefined) {
+    return ``;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string
+  const str = typeof value === `string` ? value : String(value);
+  if (
+    str.includes(`,`) ||
+    str.includes(`"`) ||
+    str.includes(`\n`) ||
+    str.includes(`\r`)
+  ) {
+    return `"${str.replace(/"/g, `""`)}"`;
+  }
+  return str;
+};
+
+const render = (result: QueryResult): Buffer => {
+  const { columns, rows } = result;
+
+  const header = columns.map(escape).join(`,`);
+  const lines = rows.map((row) =>
+    columns.map((col) => escape(row[col])).join(`,`)
+  );
+
+  const csv = [header, ...lines].join(`\n`);
+  return Buffer.from(csv, `utf-8`);
+};
+
+const CsvRenderer = { render };
+
+export default CsvRenderer;