feat: add Nsql and NsqlGenerateSql for the runtime's /v1/nsql endpoint

[krinart]

Adds text-to-SQL support to the Java SDK, matching what gospice already exposes: nsql() translates a natural-language question into SQL via the runtime's configured LLM and runs it, and nsqlGenerateSql() generates the SQL without running it.

Includes new request/response model classes, unit tests against a local mock HTTP server (no live runtime needed), and a short README section.

[Copilot]

Pull request overview

Adds Java SDK support for runtime text-to-SQL operations.

Changes:

• Adds nsql() and nsqlGenerateSql() HTTP APIs.
• Introduces NSQL request, response, schema, and field models.
• Adds mock-server tests and usage documentation.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Documents NSQL usage.
SpiceClient.java	Implements NSQL HTTP operations.
NsqlRequest.java	Models NSQL request options.
NsqlResponse.java	Models query results.
NsqlSchema.java	Models result schemas.
NsqlField.java	Models schema fields.
NsqlTest.java	Tests requests, responses, validation, and errors.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/main/java/ai/spice/SpiceClient.java:1624

• Gson returns null rather than throwing for an empty body or the valid JSON literal null, so a successful but malformed runtime response makes nsql() return null despite its response contract. Reject a null decoded value so these responses consistently surface as ExecutionException, just like other malformed bodies.

            return GSON.fromJson(new String(body, StandardCharsets.UTF_8), NsqlResponse.class);
        } catch (JsonSyntaxException err) {

src/main/java/ai/spice/NsqlRequest.java:48

• new Gson() serializes primitive booleans even at their default value, so a query-only request always includes "sample_data_enabled":false even though the option was never set. This contradicts the “only includes set fields” behavior and the referenced gospice API, which marks this field omitempty. Represent the unset state (for example with a nullable Boolean plus a false-returning getter) or build the request JSON explicitly, and assert this key is absent in the query-only test.

    @SerializedName("sample_data_enabled")
    private boolean sampleDataEnabled;

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/main/java/ai/spice/SpiceClient.java:1672

• NSQL can legitimately run beyond this shared 60-second control-plane timeout: the runtime may perform up to 10 generation/execution retries, and the Spice CLI gives this same endpoint a five-minute silence deadline. This cancels valid long-running requests after one minute, unlike gospice's caller-controlled context. Use an NSQL-specific timeout (or expose one to callers).

                    .timeout(HTTP_REQUEST_TIMEOUT)

src/main/java/ai/spice/NsqlRequest.java:90

• withDatasets(Collections.emptyList()) keeps a non-null empty list, so Gson sends "datasets":[]. This differs from the stated gospice parity: its omitempty contract omits an empty list because it means “all datasets” (spice-rs does the same). Normalize empty input to null so optional-field encoding remains consistent.

        this.datasets = datasets == null ? null : new ArrayList<>(datasets);

src/main/java/ai/spice/SpiceClient.java:1663

• Strings.isNullOrEmpty accepts whitespace-only text, so " " reaches the runtime despite the validation contract requiring a natural-language query; the current spice-rs validation explicitly rejects this case. Treat blank strings as invalid before making the HTTP call.

        if (Strings.isNullOrEmpty(request.getQuery())) {

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.