feat(interactions): add previous_interaction_id for multi-turn conversations (#5669)

# What does this PR do?

Adds `previous_interaction_id` support to the Google Interactions API,
enabling server-side conversation state for multi-turn interactions.
Without this, every request starts fresh and ADK agents cannot maintain
context across turns.

When a request includes `previous_interaction_id`, the server fetches
the stored conversation history from the SQL backend, prepends it
(including the model's prior response) to the new input, and calls
inference with the full context. Both streaming and non-streaming
responses are persisted for future chaining.

Key additions:
- `InteractionsStore` class (`src/ogx/providers/utils/interactions/`)
following the `ResponsesStore` pattern with `AuthorizedSqlStore` and
access control policy
- `InteractionsConfig` with `SqlStoreReference` for configurable SQL
backend (SQLite/Postgres)
- `_build_messages()` method for conversation history reconstruction,
supporting multi-hop chaining
- Updated Google Interactions API conformance score (39.0% → 40.2%)

## Test Plan

55 unit tests pass (37 existing + 5 new `previous_interaction_id` + 13
shape/passthrough tests). All 39 pre-commit hooks pass.

```bash
# Unit tests
uv run pytest tests/unit/providers/inline/interactions/ -x --tb=short -q

# End-to-end validation with Google GenAI SDK
OLLAMA_URL=http://localhost:11434/v1 uv run --extra starter ogx stack run starter --port 8321
uv run scripts/test_interactions_api.py --base-url http://localhost:8321 --model ollama/llama3.2:3b
```

Test 5 validates conversation chaining: creates a first interaction
establishing context ("My name is Alice"), then chains from it with
`previous_interaction_id` and verifies the model remembers the name.

---------

Signed-off-by: Sébastien Han <seb@redhat.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Francisco Javier Arceo <arceofrancisco@gmail.com>

Author: 3 people

client-sdks/stainless/openapi.yml

@@ -11847,6 +11847,11 @@ components:
             type: array
           - type: 'null'
           description: Tools (function declarations) available to the model.
+        previous_interaction_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of a previous interaction to continue the conversation from.
         stream:
           anyOf:
           - type: boolean

docs/docs/api-google-interactions/conformance.mdx

@@ -21,9 +21,9 @@ This documentation is auto-generated from the Google Interactions API specificat
 
 | Metric | Value |
 |--------|-------|
-| **Overall Coverage Score** | 39.0% |
-| **Total Items Implemented** | 32/82 |
-| **Total Missing** | 50 |
+| **Overall Coverage Score** | 40.2% |
+| **Total Items Implemented** | 33/82 |
+| **Total Missing** | 49 |
 
 ## Section Scores
 
@@ -36,7 +36,7 @@ Sections are sorted by coverage score (lowest first, needing most attention).
 | Endpoints | 25.0% | 1 | 4 | 3 |
 | GenerationConfig | 30.0% | 3 | 10 | 7 |
 | Usage | 30.0% | 3 | 10 | 7 |
-| Request Properties | 53.8% | 7 | 13 | 6 |
+| Request Properties | 61.5% | 8 | 13 | 5 |
 | Streaming Events | 71.4% | 5 | 7 | 2 |
 | Response Properties | 88.9% | 8 | 9 | 1 |
 
@@ -188,14 +188,15 @@ These properties are in the OGX implementation but not in the Google spec:
 
 ### Request Properties
 
-**Score:** 53.8% · **Implemented:** 7/13
+**Score:** 61.5% · **Implemented:** 8/13
 
 <details>
-<summary>Implemented (7)</summary>
+<summary>Implemented (8)</summary>
 
 - `generation_config`
 - `input`
 - `model`
+- `previous_interaction_id`
 - `response_modalities`
 - `stream`
 - `system_instruction`
@@ -204,10 +205,9 @@ These properties are in the OGX implementation but not in the Google spec:
 </details>
 
 <details>
-<summary>Missing (6)</summary>
+<summary>Missing (5)</summary>
 
 - `background`
-- `previous_interaction_id`
 - `response_format`
 - `response_mime_type`
 - `service_tier`

docs/docs/providers/interactions/inline_builtin.mdx

@@ -10,8 +10,18 @@ title: inline::builtin
 
 Serves the Google Interactions API (POST /v1alpha/interactions) so that Google GenAI SDK and ADK clients can call OGX without code changes. Requests are translated to OpenAI Chat Completions and routed to whichever inference provider is configured (vLLM, Ollama, OpenAI, Bedrock, etc.). When the provider is Gemini, non-streaming requests are forwarded directly to the native /v1beta/interactions endpoint, avoiding double translation.
 
+## Configuration
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `store` | `SqlStoreReference` | No | table_name='interactions' backend='sql_default' | SQL store for persisting interaction state (conversation chaining). |
+| `store.table_name` | `str` | No |  | Name of the table to use for the SqlStore |
+| `store.backend` | `str` | No |  | Name of backend from storage.backends |
+
 ## Sample Configuration
 
 ```yaml
-{}
+store:
+  table_name: interactions
+  backend: sql_default
 ```

docs/static/experimental-ogx-spec.yaml

@@ -7453,6 +7453,11 @@ components:
             type: array
           - type: 'null'
           description: Tools (function declarations) available to the model.
+        previous_interaction_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of a previous interaction to continue the conversation from.
         stream:
           anyOf:
           - type: boolean

docs/static/google-interactions-coverage.json

@@ -2,10 +2,10 @@
   "google_spec": "docs/static/google-interactions-spec.json",
   "spec_version": "v1beta",
   "summary": {
-    "overall_score": 39.0,
+    "overall_score": 40.2,
     "total_google_items": 82,
-    "total_implemented": 32,
-    "total_missing": 50
+    "total_implemented": 33,
+    "total_missing": 49
   },
   "sections": [
     {
@@ -26,21 +26,21 @@
     {
       "section": "Request Properties",
       "google_total": 13,
-      "implemented": 7,
-      "missing_count": 6,
-      "score": 53.8,
+      "implemented": 8,
+      "missing_count": 5,
+      "score": 61.5,
       "supported": [
         "generation_config",
         "input",
         "model",
+        "previous_interaction_id",
         "response_modalities",
         "stream",
         "system_instruction",
         "tools"
       ],
       "missing": [
         "background",
-        "previous_interaction_id",
         "response_format",
         "response_mime_type",
         "service_tier",

docs/static/stainless-ogx-spec.yaml

@@ -11847,6 +11847,11 @@ components:
             type: array
           - type: 'null'
           description: Tools (function declarations) available to the model.
+        previous_interaction_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of a previous interaction to continue the conversation from.
         stream:
           anyOf:
           - type: boolean

scripts/google_interactions_coverage.py

@@ -132,6 +132,7 @@ def _collect_streaming_events(spec: dict[str, Any]) -> list[str]:
     "system_instruction",
     "generation_config",
     "tools",
+    "previous_interaction_id",
     "stream",
     "response_modalities",
 }

scripts/test_interactions_api.py

@@ -55,7 +55,7 @@ def run_non_streaming_basic(client: genai.Client, model: str) -> None:
         input="What is 2+2? Reply with just the number.",
     )
 
-    assert len(interaction.id) > 0, f"ID should not be empty, got: {interaction.id}"
+    assert interaction.id.startswith("interaction-"), f"ID should start with 'interaction-', got: {interaction.id}"
     assert interaction.status == "completed", f"Status should be 'completed', got: {interaction.status}"
     assert len(interaction.outputs) > 0, "Expected at least one output"
     assert interaction.outputs[0].type == "text", f"Output type should be 'text', got: {interaction.outputs[0].type}"
@@ -234,9 +234,36 @@ def run_tool_calling(client: genai.Client, model: str) -> None:
     print("  PASSED")
 
 
+def run_previous_interaction_id(client: genai.Client, model: str) -> None:
+    """Test 6: Conversation chaining via previous_interaction_id."""
+    print("Test 6: Conversation chaining (previous_interaction_id)...")
+
+    # First interaction: establish context
+    first = client.interactions.create(
+        model=model,
+        input="My name is Alice. Remember it.",
+    )
+    assert first.status == "completed"
+    assert first.id.startswith("interaction-")
+    print(f"  First response: {first.outputs[0].text[:80]}")
+
+    # Second interaction: chain from first, ask about the context
+    second = client.interactions.create(
+        model=model,
+        input="What is my name?",
+        previous_interaction_id=first.id,
+    )
+    assert second.status == "completed"
+    text = second.outputs[0].text.lower()
+    assert "alice" in text, f"Expected 'alice' in chained response, got: {second.outputs[0].text}"
+
+    print(f"  Chained response: {second.outputs[0].text[:80]}")
+    print("  PASSED")
+
+
 def run_streaming_basic(client: genai.Client, model: str) -> None:
-    """Test 6: Streaming interaction with SSE events."""
-    print("Test 6: Streaming basic interaction...")
+    """Test 7: Streaming interaction with SSE events."""
+    print("Test 7: Streaming basic interaction...")
 
     stream = client.interactions.create(
         model=model,
@@ -269,7 +296,7 @@ def run_streaming_basic(client: genai.Client, model: str) -> None:
     full_text = "".join(text_parts)
     assert len(full_text) > 0, "Streaming should produce text"
     assert interaction_id is not None, "Should have received an interaction ID"
-    assert len(interaction_id) > 0, f"ID should not be empty, got: {interaction_id}"
+    assert interaction_id.startswith("interaction-"), f"ID should start with 'interaction-', got: {interaction_id}"
 
     print(f"  Events: {event_types}")
     print(f"  Full text: {full_text[:80]}")
@@ -316,6 +343,7 @@ def main():
         run_non_streaming_multi_turn,
         run_non_streaming_generation_config,
         run_tool_calling,
+        run_previous_interaction_id,
         run_streaming_basic,
     ]
 

src/ogx/distributions/ci-tests/config.yaml

@@ -203,6 +203,10 @@ providers:
   interactions:
   - provider_id: builtin
     provider_type: inline::builtin
+    config:
+      store:
+        table_name: interactions
+        backend: sql_default
   messages:
   - provider_id: builtin
     provider_type: inline::builtin

src/ogx/distributions/ci-tests/run-with-postgres-store.yaml

@@ -203,6 +203,10 @@ providers:
   interactions:
   - provider_id: builtin
     provider_type: inline::builtin
+    config:
+      store:
+        table_name: interactions
+        backend: sql_default
   messages:
   - provider_id: builtin
     provider_type: inline::builtin