Skip to content

Commit 77b92a5

Browse files
Alexandre Oliveiraclaude
Alexandre Oliveira
and
claude
committed
docs(turing): major documentation refactoring into focused pages
Split genai-llm.md into dedicated pages: - embedding-stores.md: ChromaDB/PgVector/Milvus + embedding model selection - tool-calling.md: full reference for all 27 native tools across 7 categories - mcp-servers.md: MCP server configuration (stdio/HTTP transport, sync/async modes) - ai-agents.md: agent composition, configuration form, execution flow diagram - genai-llm.md refactored as overview with RAG architecture and pointers Split security-keycloak.md into focused pages: - security-authentication.md: native session login + API Key (everyday reference) - security-keycloak.md: Keycloak OAuth2/OIDC full 6-step production setup only Extracted from developer-guide.md: - rest-api.md: full REST API reference (search, autocomplete, spell check, GenAI, token usage) - developer-guide.md now focused on dev environment, SDK, and contributing Updated sidebars-turing.ts, index.md, and all cross-references across: assets.md, chat.md, llm-instances.md, token-usage.md, sn-concepts.md, getting-started/core-concepts.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent dcb75a0 commit 77b92a5

17 files changed

Lines changed: 869 additions & 462 deletions

‎docs-turing/ai-agents.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
sidebar_position: 7
3+
title: AI Agents
4+
description: Configure, compose, and deploy AI Agents in Turing ES — combining LLM Instances, Tool Callings, and MCP Servers into purpose-built assistants.
5+
---
6+
7+
# AI Agents
8+
9+
An **AI Agent** is the central composition object in Turing ES's GenAI system. It combines a specific [LLM Instance](./llm-instances.md), a selected set of [Tool Callings](./tool-calling.md), and a set of [MCP Servers](./mcp-servers.md) into a single, named, deployable assistant.
10+
11+
Each agent has its own personality, capability set, and visual identity. In the **Chat** interface, every configured agent appears as a separate tab — users choose which agent to interact with based on its name and description. See the [Chat](./chat.md) page for the full interface documentation.
12+
13+
AI Agents are configured in **Administration → AI Agents**.
14+
15+
---
16+
17+
## Configuration Form
18+
19+
| Field | Description |
20+
|---|---|
21+
| **Name** | Display name shown as the tab label in the Chat interface |
22+
| **Avatar** | Image representing the agent in the chat UI |
23+
| **Description** | Brief explanation of the agent's purpose and specialization — shown below the name in the agent tab |
24+
| **LLM Instance** | The LLM provider and model this agent uses for inference. See [LLM Instances](./llm-instances.md) |
25+
| **Tool Callings** | Which of the 27 native tools are available to this agent. See [Tool Calling](./tool-calling.md) |
26+
| **MCP Servers** | Which external MCP servers this agent can call. See [MCP Servers](./mcp-servers.md) |
27+
28+
---
29+
30+
## Composing Agents for Specific Roles
31+
32+
Because each agent independently selects its LLM Instance, tools, and MCP servers, it is straightforward to build purpose-specific assistants. Give each agent a focused set of tools — a lean tool list reduces prompt length and helps the LLM make more precise tool choices.
33+
34+
**Enterprise Search Agent**
35+
36+
An agent that helps users find and explore indexed content across the organization.
37+
38+
| Field | Value |
39+
|---|---|
40+
| LLM Instance | Anthropic Claude Sonnet |
41+
| Tool Callings | `list_sites`, `search_site`, `get_document_details`, `find_similar_documents`, `search_by_date_range` |
42+
| MCP Servers | — |
43+
44+
**Data Research Agent**
45+
46+
A multi-purpose agent that can browse the web, query financial data, and run data analysis scripts.
47+
48+
| Field | Value |
49+
|---|---|
50+
| LLM Instance | OpenAI GPT-4o |
51+
| Tool Callings | `fetch_webpage`, `extract_links`, `get_stock_quote`, `get_weather`, `execute_python`, `search_knowledge_base` |
52+
| MCP Servers | Internal data API (HTTP MCP) |
53+
54+
**IT Operations Agent**
55+
56+
A local agent for internal IT queries — runs fully on-premise using a local LLM.
57+
58+
| Field | Value |
59+
|---|---|
60+
| LLM Instance | Ollama (local Llama 3) |
61+
| Tool Callings | `execute_python`, `get_current_time`, `search_knowledge_base` |
62+
| MCP Servers | Internal ticketing system (stdio MCP) |
63+
64+
---
65+
66+
## How an Agent Executes
67+
68+
When a user sends a message to an AI Agent, the following loop runs:
69+
70+
```mermaid
71+
sequenceDiagram
72+
participant User
73+
participant Turing as Turing ES
74+
participant LLM as LLM Instance
75+
participant Tool as Tool / MCP Server
76+
77+
User->>Turing: Send message
78+
Turing->>LLM: User message + system prompt + tool definitions
79+
loop Reasoning chain
80+
LLM->>Turing: Request tool call (tool name + arguments)
81+
Turing->>Tool: Execute tool
82+
Tool-->>Turing: Tool result
83+
Turing->>LLM: Tool result
84+
end
85+
LLM-->>Turing: Final response
86+
Turing-->>User: Streamed response (SSE)
87+
```
88+
89+
1. Turing ES sends the user message to the LLM along with a system prompt describing the agent and the definitions of all enabled tools.
90+
2. The LLM decides which tools (if any) to call, based on the message content and tool descriptions.
91+
3. Turing ES executes the requested tool calls — native tools or MCP server calls — and returns the results to the LLM.
92+
4. The LLM may invoke additional tools in a multi-step reasoning chain before producing a final response.
93+
5. The final response is streamed to the user via Server-Sent Events (SSE).
94+
95+
This loop continues until the LLM determines it has enough context to respond, up to a configurable maximum number of iterations.
96+
97+
---
98+
99+
## Related Pages
100+
101+
| Page | Description |
102+
|---|---|
103+
| [LLM Instances](./llm-instances.md) | Configure the LLM providers available as agent backends |
104+
| [Tool Calling](./tool-calling.md) | Full reference of all 27 native tools |
105+
| [MCP Servers](./mcp-servers.md) | Connect agents to external tools via MCP |
106+
| [Chat](./chat.md) | Front-end where agents are used — AI Agents tab |
107+
| [GenAI & LLM Configuration](./genai-llm.md) | RAG architecture overview |
108+
109+
---
110+
111+
*Previous: [MCP Servers](./mcp-servers.md) | Next: [Chat](./chat.md)*

‎docs-turing/assets.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ Once files are indexed, AI Agents can query the knowledge base via four built-in
181181
| `list_knowledge_base_files` | Lists all indexed files, with optional keyword filter |
182182
| `get_file_from_knowledge_base` | Retrieves the full indexed content of a specific file |
183183

184-
For details on configuring AI Agents and tool callings, see [Generative AI & LLM Configuration — AI Agents](./genai-llm.md#ai-agents).
184+
For details on configuring AI Agents and tool callings, see [AI Agents](./ai-agents.md) and [Tool Calling](./tool-calling.md).
185185

186186
---
187187

‎docs-turing/chat.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ description: Use the Turing ES Chat interface to interact with LLMs, AI Agents,
99
The **Chat** interface is the primary way users interact with the AI capabilities of Turing ES. It is organized into three tabs: a direct **LLM chat**, a **Semantic Navigation** chat for searching indexed sites, and dynamic **AI Agent** tabs — one per configured and enabled agent.
1010

1111
:::info LLM required
12-
The Chat interface is only available when at least one LLM Instance is configured and enabled. See [Generative AI & LLM Configuration — LLM Providers](./genai-llm.md#llm-providers) to set one up.
12+
The Chat interface is only available when at least one LLM Instance is configured and enabled. See [LLM Instances](./llm-instances.md) to set one up.
1313
:::
1414

1515
---
@@ -125,7 +125,7 @@ Each **AI Agent** configured and enabled in **Administration → AI Agents** app
125125
| **Native Tools** | A selection from the 27 native tool callings (code interpreter, search, weather, finance, etc.) |
126126
| **MCP Servers** | External tool servers connected specifically to this agent |
127127

128-
For full configuration details — composing agents, tool selection, and MCP Server registration — see [Generative AI & LLM Configuration — AI Agents](./genai-llm.md#ai-agents).
128+
For full configuration details — composing agents, tool selection, and MCP Server registration — see [AI Agents](./ai-agents.md).
129129

130130
---
131131

@@ -235,4 +235,4 @@ curl -X POST "http://localhost:2700/api/v2/llm/agent/my-agent/chat" \
235235

236236
---
237237

238-
*Previous: [Token Usage](./token-usage.md) | Next: [Architecture Overview](./architecture-overview.md)*
238+
*Previous: [AI Agents](./ai-agents.md) | Next: [Token Usage](./token-usage.md)*

‎docs-turing/developer-guide.md‎

Lines changed: 4 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -197,163 +197,11 @@ Turing ES maintains high code quality standards. You can check the project healt
197197

198198
## REST API
199199

200-
Turing ES exposes a rich REST API for integrating search and AI capabilities into any application. All endpoints use **JSON** and authenticate via an **API token** passed as a custom request header.
200+
Turing ES exposes a REST API for integrating search and AI capabilities into any application. All endpoints use **JSON**. Authentication uses the `Key` header with an API Token created in **Administration → API Tokens**.
201201

202-
### Authentication
202+
For the full endpoint reference — search, autocomplete, spell check, latest searches, GenAI chat, and token usage — see **[REST API Reference](./rest-api.md)**.
203203

204-
All API requests require a `Key` header containing the API token:
205-
206-
```
207-
Key: <YOUR_API_TOKEN>
208-
```
209-
210-
**Generating an API Token:**
211-
212-
1. Sign in to the Administration Console at `http://localhost:2700`.
213-
2. Navigate to **Administration → API Tokens**.
214-
3. Click **New** and fill in a title and description.
215-
4. Copy the generated token immediately — it will not be shown again.
216-
217-
For full details on managing users, groups, roles, and tokens, see the [Administration Guide — API Tokens](./administration-guide.md#api-tokens).
218-
219-
### OpenAPI & Swagger
220-
221-
Explore and test every endpoint interactively:
222-
223-
- **Swagger UI:** `http://localhost:2700/swagger-ui.html`
224-
- **OpenAPI 3.0 spec:** `http://localhost:2700/v3/api-docs`
225-
226-
---
227-
228-
## Semantic Navigation API
229-
230-
### Search
231-
232-
```
233-
GET | POST http://localhost:2700/api/sn/{siteName}/search
234-
```
235-
236-
The core search endpoint. Returns results, facets, spotlights, and pagination.
237-
238-
**Query Parameters:**
239-
240-
| Parameter | Required | Description |
241-
|---|---|---|
242-
| `q` | ✅ | Search query |
243-
| `p` | | Page number (default: `1`) |
244-
| `rows` | | Results per page |
245-
| `_setlocale` | ✅ | Locale (e.g., `en_US`) |
246-
| `sort` | | Sort field and direction |
247-
| `fq[]` | | Filter queries |
248-
| `tr[]` | | Targeting rules |
249-
| `group` | | Group results by field |
250-
251-
**Example:**
252-
253-
```bash
254-
curl -X GET "http://localhost:2700/api/sn/Sample/search?q=enterprise+search&p=1&_setlocale=en_US&rows=10" \
255-
-H "Key: <API_TOKEN>" \
256-
-H "Accept: application/json"
257-
```
258-
259-
---
260-
261-
### Auto Complete
262-
263-
```
264-
GET http://localhost:2700/api/sn/{siteName}/ac
265-
```
266-
267-
Returns suggestions for the given prefix — perfect for search-as-you-type UIs.
268-
269-
| Parameter | Required | Description |
270-
|---|---|---|
271-
| `q` | ✅ | Prefix to complete |
272-
| `rows` | | Max suggestions |
273-
| `_setlocale` | ✅ | Locale |
274-
275-
**Example:**
276-
277-
```bash
278-
curl "http://localhost:2700/api/sn/Sample/ac?q=enter&_setlocale=en_US"
279-
```
280-
281-
**Response:**
282-
283-
```json
284-
["enterprise", "enterprise search", "enterprise AI", "entries"]
285-
```
286-
287-
---
288-
289-
### Latest Searches
290-
291-
```
292-
POST http://localhost:2700/api/sn/{siteName}/search/latest
293-
```
294-
295-
Returns the most recent search terms for a given user — useful for personalised search history UIs.
296-
297-
| Parameter | Location | Description |
298-
|---|---|---|
299-
| `q` | Query | Current query |
300-
| `rows` | Query | Max results (default: `5`) |
301-
| `_setlocale` | Query | Locale |
302-
| `userId` | Body (JSON) | User identifier |
303-
304-
**Example:**
305-
306-
```bash
307-
curl -X POST "http://localhost:2700/api/sn/Sample/search/latest?q=cloud&rows=5&_setlocale=en_US" \
308-
-H "Key: <API_TOKEN>" \
309-
-H "Content-Type: application/json" \
310-
-d '{ "userId": "user123" }'
311-
```
312-
313-
**Response:**
314-
315-
```json
316-
["cloud computing", "cloud storage", "cloud security"]
317-
```
318-
319-
---
320-
321-
### Search Locales
322-
323-
```
324-
GET http://localhost:2700/api/sn/{siteName}/search/locales
325-
```
326-
327-
Lists all configured locales for a Semantic Navigation site.
328-
329-
**Response:**
330-
331-
```json
332-
[
333-
{ "locale": "en_US", "link": "/api/sn/Sample/search?_setlocale=en_US" },
334-
{ "locale": "pt_BR", "link": "/api/sn/Sample/search?_setlocale=pt_BR" }
335-
]
336-
```
337-
338-
---
339-
340-
### Spell Check
341-
342-
```
343-
GET http://localhost:2700/api/sn/{siteName}/{locale}/spell-check
344-
```
345-
346-
Corrects a query against the site's indexed vocabulary.
347-
348-
| Parameter | Required | Description |
349-
|---|---|---|
350-
| `q` | ✅ | Text to check |
351-
352-
**Example:**
353-
354-
```bash
355-
curl "http://localhost:2700/api/sn/Sample/en_US/spell-check?q=entirprise"
356-
```
204+
For interactive exploration, use the built-in Swagger UI at `http://localhost:2700/swagger-ui.html` or the OpenAPI spec at `http://localhost:2700/v3/api-docs`.
357205

358206
---
359207

@@ -374,4 +222,4 @@ Check the open [GitHub Issues](https://github.com/openviglet/turing/issues) for
374222

375223
---
376224

377-
*Previous: [Security & Keycloak](./security-keycloak.md) | Next: [Administration Guide](./administration-guide.md)*
225+
*Previous: [Security & Keycloak](./security-keycloak.md) | Next: [REST API Reference](./rest-api.md)*

0 commit comments

Comments
 (0)