feat: add proxyLLMCall and deprecate executeQuery

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to the AxonFlow Java SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.7.0] - 2026-01-23
+
+### Added
+
+- **proxyLLMCall()**: New primary method for Proxy Mode with improved documentation
+  - Clearly describes Proxy Mode behavior (AxonFlow makes the LLM call on your behalf)
+  - Documents when to use Proxy Mode vs Gateway Mode
+  - Both sync (`proxyLLMCall`) and async (`proxyLLMCallAsync`) variants
+
+### Deprecated
+
+- **executeQuery()**: Deprecated in favor of proxyLLMCall()
+  - Marked with `@Deprecated` annotation
+  - Will be removed in v3.0.0
+  - Logs deprecation warning in debug mode
+  - Remains functional as a wrapper around proxyLLMCall()
+
+---
+
 ## [2.6.0] - 2026-01-18
 
 ### Added

src/main/java/com/getaxonflow/sdk/AxonFlow.java

@@ -490,17 +490,30 @@ public CompletableFuture<AuditSearchResponse> getAuditLogsByTenantAsync(String t
     // ========================================================================
 
     /**
-     * Executes a query through AxonFlow (Proxy Mode).
+     * Sends a query through AxonFlow with full policy enforcement (Proxy Mode).
+     *
+     * <p>This is Proxy Mode - AxonFlow acts as an intermediary, making the LLM call on your behalf.
      *
-     * <p>In Proxy Mode, AxonFlow handles both policy enforcement and LLM routing.
-     * This is the simplest integration pattern but adds latency.
+     * <p>Use this when you want AxonFlow to:
+     * <ul>
+     *   <li>Evaluate policies before the LLM call</li>
+     *   <li>Make the LLM call to the configured provider</li>
+     *   <li>Filter/redact sensitive data from responses</li>
+     *   <li>Automatically track costs and audit the interaction</li>
+     * </ul>
+     *
+     * <p>For Gateway Mode (lower latency, you make the LLM call), use:
+     * <ul>
+     *   <li>{@link #getPolicyApprovedContext} before your LLM call</li>
+     *   <li>{@link #auditLLMCall} after your LLM call</li>
+     * </ul>
      *
      * @param request the client request
      * @return the response from AxonFlow
      * @throws PolicyViolationException if the request is blocked by policy
      * @throws AuthenticationException  if authentication fails
      */
-    public ClientResponse executeQuery(ClientRequest request) {
+    public ClientResponse proxyLLMCall(ClientRequest request) {
         Objects.requireNonNull(request, "request cannot be null");
 
         // Check cache first
@@ -528,7 +541,7 @@ public ClientResponse executeQuery(ClientRequest request) {
 
                     return result;
                 }
-            }, "executeQuery");
+            }, "proxyLLMCall");
 
             // Cache successful responses
             if (response.isSuccess() && !response.isBlocked()) {
@@ -539,14 +552,42 @@ public ClientResponse executeQuery(ClientRequest request) {
         });
     }
 
+    /**
+     * Asynchronously sends a query through AxonFlow with full policy enforcement (Proxy Mode).
+     *
+     * @param request the client request
+     * @return a future containing the response
+     * @see #proxyLLMCall(ClientRequest)
+     */
+    public CompletableFuture<ClientResponse> proxyLLMCallAsync(ClientRequest request) {
+        return CompletableFuture.supplyAsync(() -> proxyLLMCall(request), asyncExecutor);
+    }
+
+    /**
+     * Executes a query through AxonFlow (Proxy Mode).
+     *
+     * @param request the client request
+     * @return the response from AxonFlow
+     * @deprecated Use {@link #proxyLLMCall(ClientRequest)} instead. This method will be removed in v3.0.0.
+     */
+    @Deprecated
+    public ClientResponse executeQuery(ClientRequest request) {
+        if (config.isDebug()) {
+            logger.warn("DEPRECATION WARNING: executeQuery() is deprecated. Use proxyLLMCall() instead. This method will be removed in v3.0.0.");
+        }
+        return proxyLLMCall(request);
+    }
+
     /**
      * Asynchronously executes a query through AxonFlow.
      *
      * @param request the client request
      * @return a future containing the response
+     * @deprecated Use {@link #proxyLLMCallAsync(ClientRequest)} instead. This method will be removed in v3.0.0.
      */
+    @Deprecated
     public CompletableFuture<ClientResponse> executeQueryAsync(ClientRequest request) {
-        return CompletableFuture.supplyAsync(() -> executeQuery(request), asyncExecutor);
+        return proxyLLMCallAsync(request);
     }
 
     // ========================================================================