Neo4j Genai Plugin Skill

# neo4j-genai-plugin-skill

Skill for calling LLM providers directly from Cypher using the Neo4j GenAI Plugin `ai.text.*` functions [2025.12].

**Covers:**
- `ai.text.embed()` / `ai.text.embedBatch()` — generate vector embeddings in Cypher; replaces deprecated `genai.vector.encode()`
- `ai.text.completion()` / `ai.text.aggregateCompletion()` — LLM text generation over query results
- `ai.text.structuredCompletion()` / `ai.text.aggregateStructuredCompletion()` — JSON Schema-validated structured output
- `ai.text.chat()` — stateful chat with `chatId` (OpenAI / Azure only)
- `ai.text.tokenCount()` / `ai.text.chunkByTokenLimit()` — tokenization and chunking helpers
- Provider discovery: `ai.text.embed.providers()`, `ai.text.completion.providers()`
- Provider configuration — OpenAI, Azure OpenAI, VertexAI, Amazon Bedrock
- Pure-Cypher GraphRAG: embed → vector search → graph traversal → completion in one query
- CYPHER 25 requirement: per-query prefix and `ALTER DATABASE` default
- Migration from deprecated `genai.vector.*` → `ai.text.*`

**Version / compatibility:**
- `ai.text.*` requires Neo4j 2025.12+ (self-managed) or Aura with GenAI Plugin enabled
- All functions require `CYPHER 25` prefix or `ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 25`
- Provider strings are lowercase: `'openai'`, `'azure-openai'`, `'vertexai'`, `'bedrock-titan'`

**Not covered:**
- Vector index creation and management → `neo4j-vector-index-skill`
- GraphRAG pipelines via Python (`neo4j-graphrag` package) → `neo4j-graphrag-skill`
- KG construction from documents → `neo4j-document-import-skill`

**Install:**
```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-genai-plugin-skill
```

Or paste this link into your coding assistant:
https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-genai-plugin-skill


# GenAI Plugin — Full Provider Configuration Reference

All `ai.text.*` functions and `ai.text.embedBatch` accept `configuration :: MAP` as last argument.

Provider strings are **lowercase and exact** — case-sensitive.

---

## OpenAI (`'openai'`)

| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
| `token` | STRING | Yes | — | OpenAI API key |
| `model` | STRING | Yes | — | e.g. `'text-embedding-3-small'`, `'gpt-4o-mini'` |
| `maxBatchSize` | INTEGER | No | 8192 | Max tokens per batch request |
| `vendorOptions` | MAP | No | `{}` | Extra OpenAI params, e.g. `{ dimensions: 1024 }` for reduced embedding dims |
| `chatHistory` | LIST<ANY> | No | — | Completion/chat only. `[{ role: 'user', content: '...' }, ...]` |

### Embed example
```cypher
CYPHER 25
RETURN ai.text.embed('Hello', 'openai', {
  token: $openaiKey, model: 'text-embedding-3-small',
  vendorOptions: { dimensions: 1024 }
}) AS v
```

### Completion example
```cypher
CYPHER 25
RETURN ai.text.completion('Summarize: ' + $text, 'openai', {
  token: $openaiKey, model: 'gpt-4o-mini',
  vendorOptions: { instructions: 'Be concise.' }
}) AS summary
```

---

## Azure OpenAI (`'azure-openai'`)

| Key | Type | Required | Default | Notes |
|---|---|---|---|---|
| `token` | STRING | Yes | — | Azure OAuth2 bearer token |
| `resource` | STRING | Yes | — | Azure resource name (subdomain of openai.azure.com) |
| `model` | STRING | Yes | — | Deployment name in Azure portal |
| `maxBatchSize` | INTEGER | No | 8192 | Embed batch only |
| `vendorOptions` | MAP | No | `{}` | Extra Azure params |
| `chatHistory` | LIST<ANY> | No | — | Completion/chat only |

### Example
```cypher
CYPHER 25
RETURN ai.text.embed('Hello', 'azure-openai', {
  token: $azureToken,
  resource: 'my-azure-resource',
  model: 'text-embedding-3-small'
}) AS v
```

### Override Azure base URL [2026.04]

Server-side env var `GENAI_AZURE_OPENAI_BASE_URL` overrides the default `https://<resource>.openai.azure.com` for all `azure-openai` `ai.text.*` calls. Set on the Neo4j server (not the driver/client). Use for private endpoints, custom hostnames, or proxy gateways.

```bash
# neo4j.conf or sy