Feat: Add support for JSON endpoints in Conversational Search (#685)

ref: #683

Co-authored-by: djklim87 <klim@manticoresearch.com>

Author: KlimTodrik

composer.lock

@@ -12,6 +12,7 @@
 namespace Manticoresearch\Buddy\Base\Plugin\ConversationalSearch;
 
 use Manticoresearch\Buddy\Core\Error\QueryParseError;
+use Manticoresearch\Buddy\Core\ManticoreSearch\Endpoint as ManticoreEndpoint;
 use Manticoresearch\Buddy\Core\Network\Request;
 use Manticoresearch\Buddy\Core\Plugin\BasePayload;
 
@@ -24,6 +25,9 @@ final class Payload extends BasePayload {
 	public const string ACTION_DESCRIBE_MODEL = 'describe_model';
 	public const string ACTION_DROP_MODEL = 'drop_model';
 	public const string ACTION_CONVERSATION = 'conversation';
+	private const array CONVERSATION_JSON_FIELDS = [
+		'query', 'table', 'model_name', 'conversation_uuid', 'vector_field', 'fields',
+	];
 
 	/** @var string */
 	public string $action;
@@ -42,6 +46,10 @@ final class Payload extends BasePayload {
 	 * @return bool
 	 */
 	public static function hasMatch(Request $request): bool {
+		if (self::matchesJson($request)) {
+			return true;
+		}
+
 		// Check SQL patterns first
 		if (self::matchesSQL($request)) {
 			return true;
@@ -50,6 +58,22 @@ public static function hasMatch(Request $request): bool {
 		return false;
 	}
 
+	/**
+	 * Check if HTTP JSON /search request contains chat payload
+	 *
+	 * @param Request $request
+	 *
+	 * @return bool
+	 */
+	private static function matchesJson(Request $request): bool {
+		if ($request->endpointBundle !== ManticoreEndpoint::Search) {
+			return false;
+		}
+
+		$payload = simdjson_decode($request->payload, true);
+		return is_array($payload) && isset($payload['chat']) && is_array($payload['chat']);
+	}
+
 	/**
 	 * Check if SQL query matches chat patterns
 	 *
@@ -94,15 +118,125 @@ private static function matchesSQL(Request $request): bool {
 	 * @throws QueryParseError
 	 */
 	public static function fromRequest(Request $request): static {
-		$payload = new static();
-		$payload->query = $request->payload;
+		return match ($request->endpointBundle) {
+			ManticoreEndpoint::Search => static::fromJsonRequest($request),
+			default => static::fromSqlRequest($request),
+		};
+	}
+
+	/**
+	 * @param Request $request
+	 *
+	 * @return static
+	 * @throws QueryParseError
+	 */
+	protected static function fromJsonRequest(Request $request): static {
+		$self = new static();
+		$self->query = $request->payload;
+		$payload = $self->decodeJsonBody($request);
+		if (!isset($payload['chat']) || !is_array($payload['chat'])) {
+			throw QueryParseError::create('HTTP JSON body must contain chat object');
+		}
+
+		$self->parseJsonConversation($payload['chat']);
+		return $self;
+	}
+
+	/**
+	 * @param Request $request
+	 *
+	 * @return static
+	 * @throws QueryParseError
+	 */
+	protected static function fromSqlRequest(Request $request): static {
+		$self = new static();
+		$self->query = $request->payload;
+		$self->parseSQLRequest($request);
+		return $self;
+	}
+
+	/**
+	 * @param Request $request
+	 *
+	 * @return array<string, mixed>
+	 * @throws QueryParseError
+	 */
+	private function decodeJsonBody(Request $request): array {
+		if (trim($request->payload) === '') {
+			throw QueryParseError::create('HTTP JSON body is required');
+		}
 
-		// Parse SQL request only (HTTP API not supported)
-		$payload->parseSQLRequest($request);
+		$payload = simdjson_decode($request->payload, true);
+		if (!is_array($payload)) {
+			throw QueryParseError::create('HTTP JSON body must be an object');
+		}
 
 		return $payload;
 	}
 
+	/**
+	 * @param array<string, mixed> $payload
+	 *
+	 * @return void
+	 * @throws QueryParseError
+	 */
+	private function parseJsonConversation(array $payload): void {
+		$this->action = self::ACTION_CONVERSATION;
+		$hasVectorField = false;
+		$hasFields = false;
+
+		foreach ($payload as $field => $value) {
+			$this->parseJsonConversationField($field, $value, $hasVectorField, $hasFields);
+		}
+
+		if ($hasVectorField && $hasFields) {
+			throw QueryParseError::create('Use either vector_field or fields, not both');
+		}
+
+		$this->validateRequiredJsonConversationParams();
+	}
+
+	/**
+	 * @throws QueryParseError
+	 */
+	private function parseJsonConversationField(
+		string $field,
+		mixed $value,
+		bool &$hasVectorField,
+		bool &$hasFields
+	): void {
+		if (!in_array($field, self::CONVERSATION_JSON_FIELDS, true)) {
+			throw QueryParseError::create("Unknown chat JSON field: $field");
+		}
+
+		if (!is_string($value)) {
+			throw QueryParseError::create("$field must be a string");
+		}
+
+		if ($field === 'vector_field') {
+			$hasVectorField = true;
+			$this->params['fields'] = $value;
+			return;
+		}
+
+		if ($field === 'fields') {
+			$hasFields = true;
+		}
+
+		$this->params[$field] = $value;
+	}
+
+	/**
+	 * @throws QueryParseError
+	 */
+	private function validateRequiredJsonConversationParams(): void {
+		foreach (['query', 'table', 'model_name'] as $field) {
+			if (!isset($this->params[$field]) || trim($this->params[$field]) === '') {
+				throw QueryParseError::create("$field must be a non-empty string");
+			}
+		}
+	}
+
 
 	/**
 	 * Parse SQL request

src/Plugin/ConversationalSearch/Payload.php

@@ -5,14 +5,17 @@ Manticore Buddy. It searches an existing vectorized table, builds context from
 matched documents, and asks an LLM to answer using that context and the current
 conversation history.
 
-Supported commands:
+Supported SQL commands:
 
 - `CREATE CHAT MODEL`
 - `SHOW CHAT MODELS`
 - `DESCRIBE CHAT MODEL`
 - `DROP CHAT MODEL`
 - `CALL CHAT`
 
+Conversation calls are also available through the HTTP JSON `/search` endpoint.
+Chat model management remains SQL-only.
+
 ## How It Works
 
 At query time `CALL CHAT` does this:
@@ -204,8 +207,53 @@ Arguments are positional only:
 | 4 | `conversation_uuid` | No | Existing conversation id, or empty string |
 | 5 | `fields` / vector field | No | `FLOAT_VECTOR` field used in `knn(...)` |
 
-The fifth argument is stored internally as `fields` for compatibility with the
-current parser, but it must be a single vector field name.
+The table argument must be a plain table identifier, optionally qualified as
+`database.table`. The vector field argument must be a plain field identifier.
+
+## HTTP JSON Syntax
+
+Conversational Search also supports named-field HTTP JSON requests through the
+standard `/search` endpoint.
+
+Start or continue a conversation:
+
+```bash
+curl -s -X POST http://localhost:9308/search \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "chat": {
+      "query": "How is vector search different from full-text search?",
+      "table": "docs",
+      "model_name": "assistant",
+      "conversation_uuid": "search-demo-1",
+      "vector_field": "embedding"
+    }
+  }'
+```
+
+Required fields:
+
+| Field | Description |
+|---|---|
+| `query` | User question |
+| `table` | Table to search |
+| `model_name` | chat model name |
+
+Optional fields:
+
+| Field | Description |
+|---|---|
+| `conversation_uuid` | Existing conversation id. If omitted or empty, Buddy creates a new one |
+| `vector_field` | `FLOAT_VECTOR` field used in `knn(...)` |
+
+`vector_field` is the HTTP JSON name for the fifth SQL `CALL CHAT` argument.
+The legacy JSON field name `fields` is accepted as an alias, but requests must
+not include both `vector_field` and `fields`.
+
+HTTP JSON conversation responses use the same logical columns as `CALL CHAT`:
+`conversation_uuid`, `user_query`, `search_query`, `response`,
+`response_with_refs`, and `sources`. `sources` is currently returned as a JSON
+string containing the retrieved source rows.
 
 The table argument must be a plain table identifier, optionally qualified as
 `database.table`. The vector field argument must be a plain field identifier.