{"_id":"@arenza/llamaindex","_rev":"2-fb5fc9253bafc6a8e9bcb455b942890c","name":"@arenza/llamaindex","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arenza/llamaindex","version":"0.1.0","keywords":["arenza","geo","generative-engine-optimization","ai-visibility","ai-search","llm-seo","brand-mention-tracking","llamaindex","llama-index","tools","agent","openai-agent","chatgpt","claude","gemini","perplexity","copilot","grok"],"author":{"url":"https://arenza.ai","name":"Arenza","email":"hello@arenza.ai"},"license":"MIT","_id":"@arenza/llamaindex@0.1.0","maintainers":[{"name":"fooly_cooly","email":"naiqiao@hotmail.com"}],"homepage":"https://arenza.ai","bugs":{"url":"https://github.com/arenza-ai/arenza-llamaindex/issues"},"dist":{"shasum":"9d47fc5d60223c4ec9b409be816cf3e9cd13704e","tarball":"https://registry.npmjs.org/@arenza/llamaindex/-/llamaindex-0.1.0.tgz","fileCount":13,"integrity":"sha512-Jhuldx65nJU4fA+TisNrkm22XWHCq1Zc0VjxKDxxpEaSarpAHx/Q8CMmC/n+VzDN0EvAA+VZkc8EzUQiDpJpIw==","signatures":[{"sig":"MEYCIQCya5AI1m5g5gCFgtjH+iH+b3Acxpb362Dn2sQOSPgJ7gIhAI4GE6XC2U8Qj8RfpTnyYwRNuRhnZvsQ28PQdu4Boiai","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36904},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"gitHead":"92ca5e55838f169ed6eb351d0ff0992e1b6d3ef7","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"fooly_cooly","email":"naiqiao@hotmail.com"},"repository":{"url":"git+https://github.com/arenza-ai/arenza-llamaindex.git","type":"git"},"_npmVersion":"10.8.2","description":"LlamaIndex.TS tools for Arenza — let any LlamaIndex agent (OpenAIAgent / AnthropicAgent / Workflow) read AI visibility metrics, GEO opportunities, and brand mention data across ChatGPT, Claude, Gemini, Perplexity, Copilot, and Grok.","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.23.0","@arenza/mcp-client":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"llamaindex":"^0.12.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"llamaindex":">=0.8.0"},"_npmOperationalInternal":{"tmp":"tmp/llamaindex_0.1.0_1777999106479_0.216380557246852","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-05T16:38:26.405Z","modified":"2026-05-07T02:26:01.718Z","0.1.0":"2026-05-05T16:38:26.629Z"},"bugs":{"url":"https://github.com/arenza-ai/arenza-llamaindex/issues"},"author":{"url":"https://arenza.ai","name":"Arenza","email":"hello@arenza.ai"},"license":"MIT","homepage":"https://arenza.ai","keywords":["arenza","geo","generative-engine-optimization","ai-visibility","ai-search","llm-seo","brand-mention-tracking","llamaindex","llama-index","tools","agent","openai-agent","chatgpt","claude","gemini","perplexity","copilot","grok"],"repository":{"url":"git+https://github.com/arenza-ai/arenza-llamaindex.git","type":"git"},"description":"LlamaIndex.TS tools for Arenza — let any LlamaIndex agent (OpenAIAgent / AnthropicAgent / Workflow) read AI visibility metrics, GEO opportunities, and brand mention data across ChatGPT, Claude, Gemini, Perplexity, Copilot, and Grok.","maintainers":[{"email":"naiqiao@hotmail.com","name":"fooly_cooly"},{"email":"quexiaoyu1016@gmail.com","name":"xiaoyuque"}],"readme":"# arenza-llamaindex\n\n> LlamaIndex.TS tools for **Arenza** — give any LlamaIndex agent (`OpenAIAgent`, `AnthropicAgent`, `AgentWorkflow`) typed access to AI visibility metrics, GEO opportunities, and brand mention data across ChatGPT, Claude, Gemini, Perplexity, Copilot, and Grok.\n\n[Arenza](https://arenza.ai) is a Generative Engine Optimization (GEO) platform that measures how 6 leading AI assistants describe brands. This package wraps the [Arenza MCP server](https://mcp.arenza.ai) as LlamaIndex `BaseToolWithCall` instances so your existing LlamaIndex agent can answer \"how am I doing in AI search?\" without wiring custom routes — the tools have Zod schemas, GEO-keyword-rich descriptions for solid tool selection, and the same return shapes as `@arenza/mcp-client`.\n\n## Why an Arenza tool plugin (not just a fetch loop)\n\nLlamaIndex agents that need to answer \"how does ChatGPT describe my brand?\" or \"what should we fix this week to improve our AI search ranking?\" benefit from a tool with a tight schema and a clear, GEO-vocabulary description. Hand-rolling fetch calls inside an agent step loses the structured-tool affordance and forces every developer to re-derive the same parameter shapes.\n\n## Install\n\n```bash\nnpm install @arenza/llamaindex arenza-mcp-client llamaindex\n# or\npnpm add @arenza/llamaindex arenza-mcp-client llamaindex\n```\n\n`llamaindex` is a peer dependency (`>=0.8.0`). Install whichever version your app already uses.\n\n## Quick start (LlamaIndex AgentWorkflow)\n\n```ts\nimport { agent } from 'llamaindex';\nimport { openai } from '@llamaindex/openai';\nimport { ArenzaMCPClient } from '@arenza/mcp-client';\nimport { getArenzaTools } from '@arenza/llamaindex';\n\nconst client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });\n\nconst myAgent = agent({\n  llm: openai({ model: 'gpt-4o-mini' }),\n  tools: getArenzaTools(client),\n  // optional: getArenzaTools(client, { includeWrite: true })  for write tools\n});\n\nconst res = await myAgent.run(\n  'Which of our brands has the worst share of voice on Perplexity, and what wrong claims are hurting it most?',\n);\n\nconsole.log(res);\n```\n\nThe agent decides on its own which tools to call. A typical trajectory:\n\n1. `arenza_list_brands` — to enumerate the portfolio.\n2. `arenza_get_brand_overview` for each — pulling per-LLM mention counts.\n3. `arenza_list_opportunities` on the worst brand, filtered to `wrong_claim`.\n\nThen the agent stitches a natural-language answer.\n\n## Quick start (vanilla, single tool call)\n\n```ts\nimport { ArenzaMCPClient } from '@arenza/mcp-client';\nimport { getArenzaTools } from '@arenza/llamaindex';\n\nconst client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });\nconst [listBrands] = getArenzaTools(client);\n\nconst result = await listBrands.call({});\nconsole.log(JSON.parse(String(result)));\n```\n\n## Tools exposed\n\n`getArenzaTools(client)` returns 6 read-only tools by default:\n\n| Tool name | What it does |\n|---|---|\n| `arenza_list_brands` | Enumerate brands in the tenant portfolio. |\n| `arenza_get_brand_overview` | Share-of-voice + wrong-claim count + per-LLM mentions for one brand. |\n| `arenza_list_prompts` | The buyer-perspective prompts being probed for a brand, with mention rate per LLM. |\n| `arenza_list_opportunities` | Open GEO opportunities (wrong_claim, missing_canonical_page, listicle_gap, discussion_seed) with severity. |\n| `arenza_suggest_competitors` | LLM-suggested competitors to add to tracking. |\n| `arenza_suggest_prompts` | LLM-generated buyer-perspective prompts (70%+ unbranded ratio enforced). |\n\nPass `{ includeWrite: true }` to also get 4 write tools:\n\n| Tool name | What it does |\n|---|---|\n| `arenza_add_competitor` | Add a competitor to a brand's tracking list. |\n| `arenza_dismiss_competitor` | Remove a competitor (e.g. wrong suggestion). |\n| `arenza_mark_opportunity_done` | Mark a GEO opportunity as completed. |\n| `arenza_generate_geo_article` | Draft a canonical-fact article anchored to a specific finding. |\n\nWrite tools are opt-in because LlamaIndex agents can be aggressive about side effects — you usually want a human in the loop before mutating tracking config.\n\n## Schemas\n\nEach tool ships a Zod schema that LlamaIndex converts to a JSON-Schema for the underlying LLM call. For example:\n\n```ts\n// arenza_list_opportunities schema\nz.object({\n  brand_id: z.string(),\n  type: z.enum(['wrong_claim', 'missing_canonical_page', 'listicle_gap', 'discussion_seed']).optional(),\n})\n```\n\nThe descriptions are deliberately GEO-vocabulary-heavy (mentioning ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok by name; mentioning \"share of voice\", \"hallucinations\", \"AI visibility\") so when an agent's prompt mentions any of those terms the tool router has high signal.\n\n## Authentication\n\nPass an Arenza API token to the client:\n\n```ts\nconst client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });\n```\n\nGet a token at [app.arenza.ai/settings/api](https://app.arenza.ai/settings/api). For multi-tenant deployments, swap to OAuth — the MCP server publishes its OAuth metadata at [`mcp.arenza.ai/.well-known/oauth-authorization-server`](https://mcp.arenza.ai/.well-known/oauth-authorization-server).\n\n## Pattern: GEO research workflow with retrieval + Arenza\n\nA common LlamaIndex pattern is to combine your existing retrieval engine (over your docs, blog, KB) with Arenza's measured AI-search data:\n\n```ts\nimport { agent } from 'llamaindex';\nimport { ArenzaMCPClient } from '@arenza/mcp-client';\nimport { getArenzaTools } from '@arenza/llamaindex';\nimport { yourQueryEngineTool } from './your-rag.js';\n\nconst client = new ArenzaMCPClient({ token: process.env.ARENZA_TOKEN! });\n\nconst researcher = agent({\n  llm,\n  tools: [\n    yourQueryEngineTool,             // queries your own product docs\n    ...getArenzaTools(client),       // 6 GEO tools\n  ],\n});\n\nconst out = await researcher.run(\n  'For the wrong_claim about pricing on stripe.com, draft a canonical-page outline ' +\n    'using both our internal pricing docs and the Arenza opportunity context.',\n);\n```\n\nThe agent will: (1) call `arenza_list_opportunities` to find the wrong claim, (2) hit your RAG tool for the internal pricing source-of-truth, (3) compose a coherent outline.\n\n## Pattern: GEO copilot inside your existing agent\n\nIf you already have a customer-facing agent, drop the read-only Arenza tools into the existing tool array — the agent now answers \"how am I doing on AI search?\" without you wiring custom routes:\n\n```ts\nconst myAgent = agent({\n  llm,\n  tools: [\n    ...yourExistingTools,\n    ...getArenzaTools(client),  // adds 6 GEO tools\n  ],\n});\n```\n\n## Related projects\n\n- [`@arenza/mcp-client`](https://github.com/arenza-ai/arenza-mcp-client-ts) — the typed TS client this wraps.\n- [`arenza-mcp-client-python`](https://github.com/arenza-ai/arenza-mcp-client-python) — Python equivalent.\n- [`@arenza/cli`](https://github.com/arenza-ai/arenza-cli) — `npx arenza scan brand.com` for terminal scans.\n- [`@arenza/langchain`](https://github.com/arenza-ai/arenza-langchain) — same six tools wrapped for LangChain / LangGraph.\n- [`@arenza/vercel-ai-sdk`](https://github.com/arenza-ai/arenza-vercel-ai-sdk) — Vercel AI SDK provider.\n- [`arenza-zapier-actions`](https://github.com/arenza-ai/arenza-zapier-actions) — Zapier integration manifest.\n- [awesome-geo](https://github.com/arenza-ai/awesome-geo) — curated list of GEO and AI-visibility resources.\n\n## Resources\n\n- Arenza homepage: https://arenza.ai\n- Long-form GEO guides: https://arenza.ai/guides\n- AI brand reference: https://arenza.ai/llms.txt + https://arenza.ai/llms-full.txt\n- MCP server: https://mcp.arenza.ai\n- OAuth spec: https://mcp.arenza.ai/.well-known/oauth-authorization-server\n- LlamaIndex docs: https://ts.llamaindex.ai\n\n## License\n\nMIT (c) 2026 Arenza\n","readmeFilename":"README.md"}