efarmz-slackbot-data 1.0.0

package/src/domain/value-objects/QueryResult.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import QueryResult from "./QueryResult.js";
+
+describe("QueryResult", () => {
+  it("creates a query result with columns and rows", () => {
+    const columns = ["id", "name", "email"];
+    const rows = [
+      { id: 1, name: "Alice", email: "alice@example.com" },
+      { id: 2, name: "Bob", email: "bob@example.com" },
+    ];
+
+    const result = QueryResult.create(columns, rows);
+
+    expect(result.columns).toEqual(columns);
+    expect(result.rows).toEqual(rows);
+    expect(result.rowCount).toBe(2);
+  });
+
+  it("handles empty result set", () => {
+    const columns = ["id", "name"];
+    const rows: Record<string, unknown>[] = [];
+
+    const result = QueryResult.create(columns, rows);
+
+    expect(result.columns).toEqual(columns);
+    expect(result.rows).toEqual([]);
+    expect(result.rowCount).toBe(0);
+  });
+
+  it("calculates row count correctly", () => {
+    const columns = ["col1"];
+    const rows = Array.from({ length: 100 }, (_, i) => ({ col1: i }));
+
+    const result = QueryResult.create(columns, rows);
+
+    expect(result.rowCount).toBe(100);
+  });
+
+  it("preserves row data integrity", () => {
+    const columns = ["id", "value"];
+    const rows = [
+      { id: 1, value: "test", extra: "field" },
+      { id: 2, value: null },
+    ];
+
+    const result = QueryResult.create(columns, rows);
+
+    expect(result.rows[0]).toEqual(rows[0]);
+    expect(result.rows[1]).toEqual(rows[1]);
+  });
+});

package/src/domain/value-objects/QueryResult.ts

@@ -0,0 +1,18 @@
+interface QueryResult {
+  columns: string[];
+  rows: Record<string, unknown>[];
+  rowCount: number;
+}
+
+const QueryResult = {
+  create(columns: string[], rows: Record<string, unknown>[]): QueryResult {
+    return {
+      columns,
+      rows,
+      rowCount: rows.length,
+    };
+  },
+};
+
+export default QueryResult;
+export type { QueryResult };

package/src/domain/value-objects/Question.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import Question from "./Question.js";
+
+describe("Question", () => {
+  describe("create()", () => {
+    it("strips Slack mentions from the text", () => {
+      const question = Question.create(`<@U123> combien de commandes`);
+      expect(question.text).toBe(`combien de commandes`);
+    });
+
+    it("preserves the raw input unchanged", () => {
+      const raw = `<@U123> combien de commandes --sql`;
+      const question = Question.create(raw);
+      expect(question.raw).toBe(raw);
+    });
+
+    it("extracts --sql flag and removes it from text", () => {
+      const question = Question.create(`<@U123> combien de commandes --sql`);
+      expect(question.flags.showSql).toBe(true);
+      expect(question.text).toBe(`combien de commandes`);
+    });
+
+    it("extracts --debug and --no-context flags", () => {
+      const question = Question.create(`test --debug --no-context`);
+      expect(question.flags.debug).toBe(true);
+      expect(question.flags.noContext).toBe(true);
+      expect(question.flags.showSql).toBe(false);
+      expect(question.text).toBe(`test`);
+    });
+
+    it("defaults all flags to false when none are present", () => {
+      const question = Question.create(`simple question`);
+      expect(question.flags.showSql).toBe(false);
+      expect(question.flags.debug).toBe(false);
+      expect(question.flags.noContext).toBe(false);
+      expect(question.text).toBe(`simple question`);
+    });
+
+    it("handles flags anywhere in the text", () => {
+      const question = Question.create(`--sql what are my orders --debug`);
+      expect(question.flags.showSql).toBe(true);
+      expect(question.flags.debug).toBe(true);
+      expect(question.text).toBe(`what are my orders`);
+    });
+
+    it("trims whitespace after cleaning flags", () => {
+      const question = Question.create(`  --sql  what are my orders  `);
+      expect(question.text).toBe(`what are my orders`);
+    });
+
+    it("handles multiple mentions", () => {
+      const question = Question.create(
+        `<@U123> <@U456> what are my orders --sql`,
+      );
+      expect(question.text).toBe(`what are my orders`);
+      expect(question.flags.showSql).toBe(true);
+    });
+  });
+});

package/src/domain/value-objects/Question.ts

@@ -0,0 +1,22 @@
+import QuestionFlags, { type QuestionFlagsType } from "./QuestionFlags.js";
+
+class Question {
+  private constructor(
+    public readonly raw: string,
+    public readonly text: string,
+    public readonly flags: QuestionFlagsType,
+  ) {}
+
+  static create(raw: string): Question {
+    const flags = QuestionFlags.parse(raw);
+    const text = raw
+      .replace(/<@U[A-Z0-9]+>/g, ``)
+      .replace(/--sql\b/g, ``)
+      .replace(/--debug\b/g, ``)
+      .replace(/--no-context\b/g, ``)
+      .trim();
+    return new Question(raw, text, flags);
+  }
+}
+
+export default Question;

package/src/domain/value-objects/QuestionFlags.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import QuestionFlags from "./QuestionFlags.js";
+
+describe("QuestionFlags", () => {
+  describe("parse()", () => {
+    it("detects --sql flag", () => {
+      const flags = QuestionFlags.parse(`what are my orders --sql`);
+      expect(flags.showSql).toBe(true);
+      expect(flags.debug).toBe(false);
+      expect(flags.noContext).toBe(false);
+    });
+
+    it("detects --debug flag", () => {
+      const flags = QuestionFlags.parse(`what are my orders --debug`);
+      expect(flags.debug).toBe(true);
+      expect(flags.showSql).toBe(false);
+      expect(flags.noContext).toBe(false);
+    });
+
+    it("detects --no-context flag", () => {
+      const flags = QuestionFlags.parse(`what are my orders --no-context`);
+      expect(flags.noContext).toBe(true);
+      expect(flags.showSql).toBe(false);
+      expect(flags.debug).toBe(false);
+    });
+
+    it("detects multiple flags", () => {
+      const flags = QuestionFlags.parse(
+        `what are my orders --sql --debug --no-context`,
+      );
+      expect(flags.showSql).toBe(true);
+      expect(flags.debug).toBe(true);
+      expect(flags.noContext).toBe(true);
+    });
+
+    it("returns false for all flags when none present", () => {
+      const flags = QuestionFlags.parse(`simple question`);
+      expect(flags.showSql).toBe(false);
+      expect(flags.debug).toBe(false);
+      expect(flags.noContext).toBe(false);
+    });
+
+    it("detects flags at the beginning", () => {
+      const flags = QuestionFlags.parse(`--sql what are my orders`);
+      expect(flags.showSql).toBe(true);
+    });
+
+    it("detects flags in the middle", () => {
+      const flags = QuestionFlags.parse(`what --sql are my orders`);
+      expect(flags.showSql).toBe(true);
+    });
+
+    it("does not match partial flag names", () => {
+      const flags = QuestionFlags.parse(`what is --sqlalchemy --debugging`);
+      expect(flags.showSql).toBe(false);
+      expect(flags.debug).toBe(false);
+    });
+  });
+});

package/src/domain/value-objects/QuestionFlags.ts

@@ -0,0 +1,18 @@
+interface QuestionFlags {
+  readonly showSql: boolean;
+  readonly debug: boolean;
+  readonly noContext: boolean;
+}
+
+const QuestionFlags = {
+  parse(text: string): QuestionFlags {
+    return {
+      showSql: /--sql\b/.test(text),
+      debug: /--debug\b/.test(text),
+      noContext: /--no-context\b/.test(text),
+    };
+  },
+};
+
+export default QuestionFlags;
+export type { QuestionFlags as QuestionFlagsType };

package/src/domain/value-objects/ResponseRendering.ts

@@ -0,0 +1,7 @@
+enum ResponseRendering {
+  TEXT = `TEXT`,
+  TABLE = `TABLE`,
+  CSV = `CSV`,
+}
+
+export default ResponseRendering;

package/src/domain/value-objects/SqlQuery.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import SqlQuery from "./SqlQuery.js";
+import type SqlValidator from "../ports/SqlValidator.js";
+
+describe("SqlQuery", () => {
+  const mockValidator: SqlValidator = {
+    validate: (raw: string) => raw.toUpperCase(),
+  };
+
+  it("creates a validated SQL query", () => {
+    const raw = "select * from users";
+    const query = SqlQuery.create(raw, mockValidator);
+
+    expect(query.raw).toBe("SELECT * FROM USERS");
+  });
+
+  it("invokes the validator during creation", () => {
+    let validatedInput: string | null = null;
+    const validator: SqlValidator = {
+      validate: (raw: string) => {
+        validatedInput = raw;
+        return raw;
+      },
+    };
+
+    SqlQuery.create("test query", validator);
+
+    expect(validatedInput).toBe("test query");
+  });
+
+  it("stores the validated SQL string", () => {
+    const validator: SqlValidator = {
+      validate: (raw: string) => `/* validated */ ${raw}`,
+    };
+
+    const query = SqlQuery.create("select 1", validator);
+
+    expect(query.raw).toBe("/* validated */ select 1");
+  });
+});

package/src/domain/value-objects/SqlQuery.ts

@@ -0,0 +1,12 @@
+import type SqlValidator from "@/domain/ports/SqlValidator.js";
+
+class SqlQuery {
+  private constructor(public readonly raw: string) {}
+
+  static create(raw: string, validator: SqlValidator): SqlQuery {
+    const validated = validator.validate(raw);
+    return new SqlQuery(validated);
+  }
+}
+
+export default SqlQuery;

package/src/domain/value-objects/ThreadId.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import ThreadId from "./ThreadId.js";
+
+describe("ThreadId", () => {
+  it("creates a ThreadId with valid channelId and threadTs", () => {
+    const threadId = ThreadId.create("C123", "1234567890.123456");
+
+    expect(threadId.channelId).toBe("C123");
+    expect(threadId.threadTs).toBe("1234567890.123456");
+  });
+
+  it("throws error when channelId is empty", () => {
+    expect(() => ThreadId.create("", "1234567890.123456")).toThrow(
+      `ThreadId.channelId cannot be empty`,
+    );
+  });
+
+  it("throws error when threadTs is empty", () => {
+    expect(() => ThreadId.create("C123", "")).toThrow(
+      `ThreadId.threadTs cannot be empty`,
+    );
+  });
+
+  it("serializes to string in format 'channelId:threadTs'", () => {
+    const threadId = ThreadId.create("C123", "1234567890.123456");
+
+    expect(threadId.toString()).toBe("C123:1234567890.123456");
+  });
+
+  it("parses serialized string back to ThreadId", () => {
+    const original = ThreadId.create("C456", "9876543210.654321");
+    const serialized = original.toString();
+    const parsed = ThreadId.parse(serialized);
+
+    expect(parsed.channelId).toBe(original.channelId);
+    expect(parsed.threadTs).toBe(original.threadTs);
+  });
+
+  it("parse().toString() returns the original serialized value", () => {
+    const serialized = "C789:5555555555.555555";
+    const threadId = ThreadId.parse(serialized);
+
+    expect(threadId.toString()).toBe(serialized);
+  });
+
+  it("throws error on invalid serialized format", () => {
+    expect(() => ThreadId.parse("invalid-no-colon")).toThrow(
+      `Invalid ThreadId format: expected "channelId:threadTs", got "invalid-no-colon"`,
+    );
+  });
+
+  it("throws error on partially invalid serialized format", () => {
+    expect(() => ThreadId.parse("C123:")).toThrow(
+      `Invalid ThreadId format: expected "channelId:threadTs", got "C123:"`,
+    );
+  });
+
+  it("handles colon in threadTs correctly", () => {
+    const threadId = ThreadId.create("C123", "1234567890.123456");
+    const serialized = threadId.toString();
+
+    expect(serialized).toBe("C123:1234567890.123456");
+    const parsed = ThreadId.parse(serialized);
+
+    expect(parsed.channelId).toBe("C123");
+    expect(parsed.threadTs).toBe("1234567890.123456");
+  });
+});

package/src/domain/value-objects/ThreadId.ts

@@ -0,0 +1,27 @@
+class ThreadId {
+  private constructor(
+    public readonly channelId: string,
+    public readonly threadTs: string,
+  ) {}
+
+  static create(channelId: string, threadTs: string): ThreadId {
+    if (!channelId) throw new Error(`ThreadId.channelId cannot be empty`);
+    if (!threadTs) throw new Error(`ThreadId.threadTs cannot be empty`);
+    return new ThreadId(channelId, threadTs);
+  }
+
+  static parse(serialized: string): ThreadId {
+    const [channelId, threadTs] = serialized.split(`:`);
+    if (!channelId || !threadTs) {
+      throw new Error(`Invalid ThreadId format: expected "channelId:threadTs", got "${serialized}"`);
+    }
+    return ThreadId.create(channelId, threadTs);
+  }
+
+  toString(): string {
+    return `${this.channelId}:${this.threadTs}`;
+  }
+}
+
+export default ThreadId;
+export type { ThreadId };

package/src/domain/value-objects/index.ts

@@ -0,0 +1,13 @@
+export { default as LLMProviderName } from "./LLMProviderName.js";
+
+export { default as Question } from "./Question.js";
+
+export { default as QuestionFlags } from "./QuestionFlags.js";
+
+export { default as QueryResult } from "./QueryResult.js";
+
+export { default as ResponseRendering } from "./ResponseRendering.js";
+
+export { default as SqlQuery } from "./SqlQuery.js";
+
+export { default as ThreadId } from "./ThreadId.js";

package/src/infrastructure/llm/AnthropicLLMProvider.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type Anthropic from "@anthropic-ai/sdk";
+import AnthropicLLMProvider from "./AnthropicLLMProvider.js";
+import type SchemaCatalog from "@/domain/ports/SchemaCatalog.js";
+import type { LLMRequest } from "@/domain/ports/LLMProvider.js";
+import LLMError from "@/domain/errors/LLMError.js";
+
+describe(`AnthropicLLMProvider`, () => {
+  let mockClient: Anthropic;
+  let mockSchemaCatalog: SchemaCatalog;
+  let provider: AnthropicLLMProvider;
+
+  beforeEach(() => {
+    mockClient = {
+      messages: {
+        create: vi.fn(),
+      },
+    } as unknown as Anthropic;
+
+    mockSchemaCatalog = {
+      getDocumentation: vi.fn().mockReturnValue(`--- schema.md ---
+Table: users
+- id: UUID
+- name: VARCHAR`),
+    };
+
+    provider = new AnthropicLLMProvider(
+      mockClient,
+      `claude-3-5-sonnet-20241022`,
+      mockSchemaCatalog,
+    );
+  });
+
+  it(`should build system prompt with schema caching`, async () => {
+    const request: LLMRequest = {
+      systemPrompt: `You are an assistant`,
+      messages: [{ role: `user`, content: `Hello` }],
+    };
+
+    const mockResponse: Anthropic.Message = {
+      id: `msg_123`,
+      type: `message`,
+      role: `assistant`,
+      content: [
+        { type: `text`, text: `Hi there` },
+      ],
+      model: `claude-3-5-sonnet-20241022`,
+      stop_reason: `end_turn`,
+      stop_sequence: null,
+      usage: { input_tokens: 10, output_tokens: 5 },
+    };
+
+    vi.mocked(mockClient.messages.create).mockResolvedValueOnce(mockResponse);
+
+    await provider.generate(request);
+
+    const callArgs = vi.mocked(mockClient.messages.create).mock.calls[0]?.[0];
+    expect(callArgs?.system).toBeInstanceOf(Array);
+    expect((callArgs?.system as Array<unknown>)?.length).toBe(2);
+
+    const systemPrompt = callArgs?.system as Array<{
+      type: string;
+      cache_control?: { type: string };
+    }>;
+    expect(systemPrompt[0]?.type).toBe(`text`);
+    expect(systemPrompt[1]?.cache_control).toEqual({ type: `ephemeral` });
+  });
+
+  it(`should call Anthropic API with correct parameters`, async () => {
+    const request: LLMRequest = {
+      systemPrompt: `You are an assistant`,
+      messages: [
+        { role: `user`, content: `What is 2+2?` },
+        { role: `assistant`, content: `4` },
+      ],
+      tools: [
+        {
+          name: `run_sql`,
+          description: `Execute SQL`,
+          inputSchema: { type: `object` },
+        },
+      ],
+    };
+
+    const mockResponse: Anthropic.Message = {
+      id: `msg_456`,
+      type: `message`,
+      role: `assistant`,
+      content: [{ type: `text`, text: `The answer is 4` }],
+      model: `claude-3-5-sonnet-20241022`,
+      stop_reason: `end_turn`,
+      stop_sequence: null,
+      usage: { input_tokens: 20, output_tokens: 10 },
+    };
+
+    vi.mocked(mockClient.messages.create).mockResolvedValueOnce(mockResponse);
+
+    await provider.generate(request);
+
+    expect(vi.mocked(mockClient.messages.create)).toHaveBeenCalledOnce();
+    const callArgs = vi.mocked(mockClient.messages.create).mock.calls[0]?.[0];
+
+    expect(callArgs?.model).toBe(`claude-3-5-sonnet-20241022`);
+    expect(callArgs?.max_tokens).toBe(4096);
+    expect((callArgs?.messages as unknown[])?.length).toBe(2);
+    expect((callArgs?.tools as unknown[])?.length).toBe(1);
+  });
+
+  it(`should return LLMResponse with correct structure`, async () => {
+    const request: LLMRequest = {
+      systemPrompt: `You are an assistant`,
+      messages: [{ role: `user`, content: `Query data` }],
+    };
+
+    const mockResponse: Anthropic.Message = {
+      id: `msg_789`,
+      type: `message`,
+      role: `assistant`,
+      content: [{ type: `text`, text: `Here is the data` }],
+      model: `claude-3-5-sonnet-20241022`,
+      stop_reason: `end_turn`,
+      stop_sequence: null,
+      usage: { input_tokens: 15, output_tokens: 8 },
+    };
+
+    vi.mocked(mockClient.messages.create).mockResolvedValueOnce(mockResponse);
+
+    const response = await provider.generate(request);
+
+    expect(response.content).toBe(`Here is the data`);
+    expect(response.stopReason).toBe(`end_turn`);
+    expect(response.inputTokens).toBe(15);
+    expect(response.outputTokens).toBe(8);
+    expect(response.toolUses).toEqual([]);
+  });
+
+  it(`should wrap Anthropic errors in LLMError`, async () => {
+    const request: LLMRequest = {
+      systemPrompt: `You are an assistant`,
+      messages: [{ role: `user`, content: `Hello` }],
+    };
+
+    const error = new Error(`API rate limit exceeded`);
+    vi.mocked(mockClient.messages.create).mockRejectedValueOnce(error);
+
+    try {
+      await provider.generate(request);
+      expect.fail(`Should have thrown LLMError`);
+    } catch (err) {
+      expect(err).toBeInstanceOf(LLMError);
+      if (err instanceof LLMError) {
+        expect(err.provider).toBe(`anthropic`);
+        expect(err.details).toBe(`API rate limit exceeded`);
+      }
+    }
+  });
+
+  it(`should call getDocumentation on schema catalog`, async () => {
+    const request: LLMRequest = {
+      systemPrompt: `You are an assistant`,
+      messages: [{ role: `user`, content: `Hello` }],
+    };
+
+    const mockResponse: Anthropic.Message = {
+      id: `msg_999`,
+      type: `message`,
+      role: `assistant`,
+      content: [{ type: `text`, text: `Response` }],
+      model: `claude-3-5-sonnet-20241022`,
+      stop_reason: `end_turn`,
+      stop_sequence: null,
+      usage: { input_tokens: 10, output_tokens: 5 },
+    };
+
+    vi.mocked(mockClient.messages.create).mockResolvedValueOnce(mockResponse);
+
+    await provider.generate(request);
+
+    expect(
+      vi.mocked(mockSchemaCatalog.getDocumentation),
+    ).toHaveBeenCalledOnce();
+  });
+
+  it(`should handle tool uses in response`, async () => {
+    const request: LLMRequest = {
+      systemPrompt: `You are an assistant`,
+      messages: [{ role: `user`, content: `Get user count` }],
+      tools: [
+        {
+          name: `run_sql`,
+          description: `Execute SQL`,
+          inputSchema: { type: `object` },
+        },
+      ],
+    };
+
+    const mockResponse: Anthropic.Message = {
+      id: `msg_tool`,
+      type: `message`,
+      role: `assistant`,
+      content: [
+        { type: `text`, text: `Let me execute:` },
+        {
+          type: `tool_use`,
+          id: `tool_call_1`,
+          name: `run_sql`,
+          input: { sql: `SELECT COUNT(*) FROM users` },
+        } as unknown as Anthropic.ToolUseBlock,
+      ],
+      model: `claude-3-5-sonnet-20241022`,
+      stop_reason: `tool_use`,
+      stop_sequence: null,
+      usage: { input_tokens: 25, output_tokens: 15 },
+    };
+
+    vi.mocked(mockClient.messages.create).mockResolvedValueOnce(mockResponse);
+
+    const response = await provider.generate(request);
+
+    expect(response.content).toBe(`Let me execute:`);
+    expect(response.toolUses).toHaveLength(1);
+    expect(response.toolUses[0]).toEqual({
+      id: `tool_call_1`,
+      name: `run_sql`,
+      input: { sql: `SELECT COUNT(*) FROM users` },
+    });
+    expect(response.stopReason).toBe(`tool_use`);
+  });
+});

package/src/infrastructure/llm/AnthropicLLMProvider.ts

@@ -0,0 +1,45 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type LLMProvider from "@/domain/ports/LLMProvider.js";
+import type {
+  LLMRequest,
+  LLMResponse,
+} from "@/domain/ports/LLMProvider.js";
+import type SchemaCatalog from "@/domain/ports/SchemaCatalog.js";
+import LLMError from "@/domain/errors/LLMError.js";
+import SystemPromptBuilder from "./prompts/SystemPromptBuilder.js";
+import AnthropicMessageMapper from "./mappers/AnthropicMessageMapper.js";
+
+class AnthropicLLMProvider implements LLMProvider {
+  constructor(
+    private readonly client: Anthropic,
+    private readonly model: string,
+    private readonly schemaCatalog: SchemaCatalog,
+  ) {}
+
+  async generate(request: LLMRequest): Promise<LLMResponse> {
+    try {
+      const schemaDoc = this.schemaCatalog.getDocumentation();
+      const systemPrompt = SystemPromptBuilder.build(schemaDoc);
+
+      const response = await this.client.messages.create({
+        model: this.model,
+        max_tokens: 4096,
+        system: systemPrompt as unknown as string | Anthropic.TextBlockParam[],
+        messages: AnthropicMessageMapper.toSDK(request.messages),
+        tools: request.tools?.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.inputSchema,
+        })) as Anthropic.Tool[] | undefined,
+      });
+
+      return AnthropicMessageMapper.fromSDK(response);
+    } catch (err) {
+      const errorMessage =
+        err instanceof Error ? err.message : String(err);
+      throw new LLMError(`anthropic`, errorMessage);
+    }
+  }
+}
+
+export default AnthropicLLMProvider;

package/src/infrastructure/llm/index.ts

@@ -0,0 +1,4 @@
+export { default as AnthropicLLMProvider } from "./AnthropicLLMProvider.js";
+export { default as SystemPromptBuilder } from "./prompts/SystemPromptBuilder.js";
+export { default as AnthropicMessageMapper } from "./mappers/AnthropicMessageMapper.js";
+export { default as ToolDefinitions } from "./prompts/ToolDefinitions.js";