clippy-graph 1.0.0

package/.claude/ralph-loop.local.md

@@ -0,0 +1,9 @@
+---
+active: true
+iteration: 1
+max_iterations: 13
+completion_promise: null
+started_at: "2026-02-03T19:46:57Z"
+---
+
+Crie uma CLI em bun + ollama api cloud para traduzir linguagem natural para query de linguagem de grafo para o neo4j --complete-promise DONE

package/bun.lock

@@ -0,0 +1,30 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "clippy-graph",
+      "dependencies": {
+        "commander": "^14.0.3",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.8", "", { "dependencies": { "bun-types": "1.3.8" } }, "sha512-3LvWJ2q5GerAXYxO2mffLTqOzEu5qnhEAlh48Vnu8WQfnmSwbgagjGZV6BoHKJztENYEDn6QmVd949W4uESRJA=="],
+
+    "@types/node": ["@types/node@25.2.0", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-DZ8VwRFUNzuqJ5khrvwMXHmvPe+zGayJhr2CDNiKB1WBE1ST8Djl00D0IC4vvNmHMdj6DlbYRIaFE7WHjlDl5w=="],
+
+    "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="],
+
+    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/index.ts

@@ -0,0 +1,3 @@
+export { translate } from "./src/translate";
+export { chatCompletion } from "./src/provider";
+export type * from "./src/types";

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "clippy-graph",
+  "version": "1.0.0",
+  "description": "Translate natural language to Neo4j Cypher queries using LLMs (Ollama / OpenRouter)",
+  "type": "module",
+  "module": "index.ts",
+  "bin": {
+    "clippy-graph": "src/cli.ts"
+  },
+  "scripts": {
+    "start": "bun run src/cli.ts"
+  },
+  "keywords": ["neo4j", "cypher", "natural-language", "llm", "ollama", "openrouter", "graph-database"],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { translate } from "./translate";
+import type { Provider, ProviderConfig } from "./types";
+
+const program = new Command();
+
+program
+  .name("clippy-graph")
+  .description("Translate natural language to Neo4j Cypher queries")
+  .version("1.0.0");
+
+program
+  .option(
+    "-p, --provider <provider>",
+    "LLM provider: ollama or openrouter",
+    process.env.CLIPPY_PROVIDER ?? "openrouter"
+  )
+  .option(
+    "-m, --model <model>",
+    "Model name to use",
+    process.env.CLIPPY_MODEL
+  )
+  .option(
+    "--ollama-host <host>",
+    "Ollama API host",
+    process.env.OLLAMA_HOST ?? "http://localhost:11434"
+  )
+  .option(
+    "--openrouter-key <key>",
+    "OpenRouter API key",
+    process.env.OPENROUTER_API_KEY
+  )
+  .option(
+    "-s, --schema <schema>",
+    "Graph schema description for better results (e.g. '(:Person {name, age})-[:KNOWS]->(:Person)')"
+  );
+
+// Default command: translate
+program
+  .argument("[question...]", "Natural language to translate to Cypher")
+  .action(async (questionParts: string[], opts) => {
+    if (questionParts.length === 0) {
+      program.help();
+      return;
+    }
+
+    const question = questionParts.join(" ");
+    const config = resolveConfig(opts);
+
+    try {
+      const result = await translate(question, config, opts.schema);
+      // Output just the cypher to stdout so it can be piped
+      console.log(result.cypher);
+
+      if (result.explanation) {
+        console.error(`\n-- ${result.explanation}`);
+      }
+    } catch (err) {
+      console.error(
+        `error: ${err instanceof Error ? err.message : String(err)}`
+      );
+      process.exit(1);
+    }
+  });
+
+// Interactive REPL
+program
+  .command("repl")
+  .description("Interactive mode — type questions, get Cypher")
+  .action(async () => {
+    const opts = program.opts();
+    const config = resolveConfig(opts);
+
+    console.error("clippy-graph repl — type a question, get Cypher. Ctrl+C to exit.\n");
+
+    const prompt = "> ";
+    process.stdout.write(prompt);
+
+    for await (const line of readLines()) {
+      const input = line.trim();
+      if (!input) {
+        process.stdout.write(prompt);
+        continue;
+      }
+
+      try {
+        const result = await translate(input, config, opts.schema);
+        console.log(`\n${result.cypher}`);
+        if (result.explanation) {
+          console.error(`-- ${result.explanation}`);
+        }
+        console.log("");
+      } catch (err) {
+        console.error(
+          `error: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+
+      process.stdout.write(prompt);
+    }
+  });
+
+function resolveConfig(opts: {
+  provider: string;
+  model?: string;
+  ollamaHost?: string;
+  openrouterKey?: string;
+}): ProviderConfig {
+  const provider = opts.provider as Provider;
+
+  if (provider !== "ollama" && provider !== "openrouter") {
+    console.error(`error: unknown provider "${provider}". Use ollama or openrouter.`);
+    process.exit(1);
+  }
+
+  const defaultModel =
+    provider === "ollama"
+      ? "llama3.1"
+      : "nvidia/nemotron-3-nano-30b-a3b:free";
+
+  return {
+    provider,
+    model: opts.model ?? defaultModel,
+    ollamaHost: opts.ollamaHost,
+    openrouterApiKey: opts.openrouterKey ?? process.env.OPENROUTER_API_KEY,
+  };
+}
+
+async function* readLines(): AsyncGenerator<string> {
+  const decoder = new TextDecoder();
+  const reader = Bun.stdin.stream().getReader();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      yield line;
+    }
+  }
+  if (buffer) yield buffer;
+}
+
+program.parse();

package/src/provider.ts

@@ -0,0 +1,78 @@
+import type { ChatMessage, ProviderConfig } from "./types";
+
+export async function chatCompletion(
+  config: ProviderConfig,
+  messages: ChatMessage[]
+): Promise<string> {
+  if (config.provider === "ollama") {
+    return ollamaChat(config, messages);
+  }
+  return openrouterChat(config, messages);
+}
+
+async function ollamaChat(
+  config: ProviderConfig,
+  messages: ChatMessage[]
+): Promise<string> {
+  const host = config.ollamaHost ?? "http://localhost:11434";
+  const url = `${host.replace(/\/$/, "")}/api/chat`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: config.model,
+      messages,
+      stream: false,
+      options: { temperature: 0.1 },
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Ollama error (${res.status}): ${body}`);
+  }
+
+  const data = (await res.json()) as { message: { content: string } };
+  return data.message.content;
+}
+
+async function openrouterChat(
+  config: ProviderConfig,
+  messages: ChatMessage[]
+): Promise<string> {
+  const apiKey = config.openrouterApiKey;
+  if (!apiKey) {
+    throw new Error(
+      "OPENROUTER_API_KEY is required when using the openrouter provider."
+    );
+  }
+
+  const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: config.model,
+      messages,
+      temperature: 0.1,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`OpenRouter error (${res.status}): ${body}`);
+  }
+
+  const data = (await res.json()) as {
+    choices: { message: { content: string } }[];
+  };
+
+  if (!data.choices?.[0]?.message?.content) {
+    throw new Error("OpenRouter returned an empty response.");
+  }
+
+  return data.choices[0].message.content;
+}

package/src/translate.ts

@@ -0,0 +1,77 @@
+import type { ChatMessage, ProviderConfig, TranslationResult } from "./types";
+import { chatCompletion } from "./provider";
+
+const SYSTEM_PROMPT = `You are a Cypher query expert for Neo4j graph databases.
+Your sole job is to translate natural language into valid Cypher queries.
+
+RULES:
+1. Output ONLY valid Cypher. No markdown fences, no explanations before or after.
+2. Use standard Neo4j Cypher syntax.
+3. For string matching, prefer case-insensitive matching with toLower() or CONTAINS.
+4. Use parameters ($param) when the user provides specific values.
+5. Unless the user specifies a limit, add LIMIT 25.
+6. For aggregations, include ORDER BY when it makes sense.
+7. Use descriptive variable names (person, company, movie — not n, m, r).
+
+RESPONSE FORMAT — strictly follow this:
+
+CYPHER:
+<the cypher query, raw, no backticks>
+
+EXPLANATION:
+<one sentence explaining the query>`;
+
+export async function translate(
+  naturalLanguage: string,
+  config: ProviderConfig,
+  schema?: string
+): Promise<TranslationResult> {
+  const messages: ChatMessage[] = [
+    { role: "system", content: buildPrompt(schema) },
+    { role: "user", content: naturalLanguage },
+  ];
+
+  const raw = await chatCompletion(config, messages);
+  return parseResponse(raw);
+}
+
+function buildPrompt(schema?: string): string {
+  if (!schema) return SYSTEM_PROMPT;
+
+  return `${SYSTEM_PROMPT}
+
+DATABASE SCHEMA (use these exact labels, types and properties):
+${schema}`;
+}
+
+function parseResponse(content: string): TranslationResult {
+  // Try structured format first
+  const cypherMatch = content.match(/CYPHER:\s*\n([\s\S]*?)(?:\nEXPLANATION:|\n*$)/i);
+  const explanationMatch = content.match(/EXPLANATION:\s*\n?([\s\S]*?)$/i);
+
+  if (cypherMatch) {
+    return {
+      cypher: cleanCypher(cypherMatch[1]),
+      explanation: explanationMatch?.[1]?.trim() ?? "",
+    };
+  }
+
+  // Fallback: extract any Cypher-looking statement
+  const fallback = content.match(
+    /((?:MATCH|CREATE|MERGE|DELETE|RETURN|WITH|CALL|UNWIND|OPTIONAL\s+MATCH)[\s\S]*)/i
+  );
+
+  return {
+    cypher: cleanCypher(fallback?.[1] ?? content),
+    explanation: "",
+  };
+}
+
+function cleanCypher(raw: string): string {
+  return raw
+    .replace(/```cypher\s*/g, "")
+    .replace(/```\s*/g, "")
+    .replace(/^CYPHER:\s*/im, "")
+    .trim()
+    .replace(/;\s*$/, "");
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+export type Provider = "ollama" | "openrouter";
+
+export interface ProviderConfig {
+  provider: Provider;
+  model: string;
+  ollamaHost?: string;
+  openrouterApiKey?: string;
+}
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface TranslationResult {
+  cypher: string;
+  explanation: string;
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}