Commit 3abd813a authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

docs: update traffic influence documentation to reflect new device handling and tool count

parent 15443bb6

ai2/implementation-and-delivery.md

+1 −1
Changes for ai2/implementation-and-delivery.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -237,7 +237,7 @@ Unspecified means no reason has been agreed. 
| `/debug/objgraph` needs no token (F9) | Unspecified | Keep the agent `ClusterIP` |

| The system prompt ends mid-sentence; `TOOL_USING_ASSISTANT_PROMPT` and `UserPhoneInput` are unused | Unspecified | None |

| What happens at the 20-model-call limit is not verified | Unspecified | None |

| READMEs are out of date: 11 of 19 tools listed, "Quart backend", other defaults | Unspecified | Use this spec |

| READMEs are out of date: "Quart backend", other defaults | Unspecified | Use this spec |

| The portal keeps the conversation list only in the browser tab ([portal §U.9](/portal/implementation-and-delivery.md)) | Accepted for now in the portal's spec | — |



---

ai2/interface-contract.md

+2 −0
Changes for ai2/interface-contract.md: 2 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -141,6 +141,7 @@ pending." A non-JSON success body comes back as `{"status_code", "body"}`. 
| Tool | Arguments | OEG call | Result |

|---|---|---|---|

| `create_traffic_influence` | `inp`: traffic influence request (§3.2) | `POST /traffic-influences` | OEG's object. Creation does not mean the influence is active yet |

| `create_traffic_influence_device` | `inp`: traffic influence request with `device` (§3.2) | `POST /traffic-influence-devices` | OEG's object. Creation does not mean the influence is active yet |

| `get_traffic_influences` | `appId` | `GET /traffic-influences` | `{"trafficInfluences": [...]}`. OEG must answer a list |

| `get_traffic_influence` | `trafficInfluenceID` | `GET /traffic-influences/{trafficInfluenceID}` | OEG's object |

| `delete_traffic_influence` | `trafficInfluenceID` | `DELETE /traffic-influences/{trafficInfluenceID}` | Pending |
@@ -185,6 +186,7 @@ and `qosStatus` (`REQUESTED`, `AVAILABLE`, `UNAVAILABLE`). `statusInfo` is `DURA 
| `appId` | Required UUID |

| `appInstanceId`, `edgeCloudZoneId` | Optional UUIDs |

| `edgeCloudRegion` | Optional string |

| `device` | `create_traffic_influence_device` only. Optional here; same rules as §3.1. OEG requires it, since no token claim maps to a device ([oeg/overview-and-architecture.md F4](/oeg/overview-and-architecture.md#f-open-questions)), and accepts only a device with `ipv4Address`. Without one: `422`/`MISSING_IDENTIFIER`; other identifiers alone: `422`/`SERVICE_NOT_APPLICABLE` |

| `sourceTrafficFilters.sourcePort`, `destinationTrafficFilters.destinationPort` | 0–65535 |

| `destinationTrafficFilters.destinationProtocol` | String |

| `subscriptionRequest.protocol` | `HTTP`, `MQTT3`, `MQTT5`, `AMQP`, `NATS`, `KAFKA` |

ai2/overview-and-architecture.md

+2 −2
Changes for ai2/overview-and-architecture.md: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -49,7 +49,7 @@ written to disk. 
             |  MCP over HTTP (/mcp), same Bearer token

             v

  +----------------------+

  | MCP server (FastMCP) |  19 tools

  | MCP server (FastMCP) |  20 tools

  | ai2-mcp :8004        |

  +----------+-----------+

             |  HTTPS/HTTP, same Bearer token
@@ -121,7 +121,7 @@ Platform-wide terms, including MCP, A2A and API product: [platform/glossary.md]( 
| UC-AI2-02 | Receive the answer as a server-sent event stream | Callers with a token |

| UC-AI2-03 | Register, list, read and delete application definitions; list edge cloud zones; create, list and delete application instances and deployments | As far as OEG allows |

| UC-AI2-04 | Create, read and delete Quality on Demand sessions | As far as OEG allows |

| UC-AI2-05 | Create, list, read and delete traffic influence resources | As far as OEG allows |

| UC-AI2-05 | Create traffic influence for an application or one device; list, read and delete traffic influence resources | As far as OEG allows |

| UC-AI2-06 | Retrieve a device's location area | As far as OEG allows |

| UC-AI2-07 | Continue a conversation using its recent turns | Any caller that sends a `session_id`, when Redis is configured |

| UC-AI2-08 | Use AI²'s tools from another MCP client | Status open (F9) |

ai2/requirements-and-design.md

+5 −5
Changes for ai2/requirements-and-design.md: 5 added lines, 5 removed lines.
Original line number Diff line number Diff line
@@ -75,7 +75,7 @@ Payloads and examples: [contract §1](/ai2/interface-contract.md). 
| `/mcp` | MCP over Streamable HTTP. The agent's `MCP_SERVER_URL` points here |

| `/health` | `200 healthy` (plain text) while the process runs. `/health/` answers `404` |



The server offers 19 tools (§K.1). Each one is listed by name in `SAFE_TOOLS` in

The server offers 20 tools (§K.1). Each one is listed by name in `SAFE_TOOLS` in

`mcp_module/app.py`. A function not on that list is never offered, even if it exists in `tools/`.



---
@@ -172,13 +172,13 @@ Why: [platform §Agentic AI Integration](/platform/architecture.md) (REQ-AI2-02) 
|---|---|---|

| Edge Application Management | `get_app_definitions`, `register_app_definition`, `get_app_definition`, `delete_app_definition`, `get_edge_cloud_zones`, `instantiate_app`, `get_app_instances`, `delete_app_instance`, `create_app_deployment`, `get_app_deployments`, `delete_app_deployment` | `edge-application-management/v0.1alpha1` |

| Quality on Demand | `create_qod_session_oai`, `get_qod_session_oai`, `delete_qod_session_oai` | `quality-on-demand/v1` |

| Traffic Influence | `create_traffic_influence`, `get_traffic_influences`, `get_traffic_influence`, `delete_traffic_influence` | `traffic-influence/v0.10` |

| Traffic Influence | `create_traffic_influence`, `create_traffic_influence_device`, `get_traffic_influences`, `get_traffic_influence`, `delete_traffic_influence` | `traffic-influence/v0.10` |

| Location Retrieval | `retrieve_location` | `location-retrieval/v0.5` |



Each tool's OEG operation, inputs and result: [contract §2](/ai2/interface-contract.md).



These OEG CAMARA operations have no tool: QoD `extend` and `retrieve-sessions`, Traffic Influence

`traffic-influence-devices` and `PATCH`, deployment `PATCH` and `clusters`. OEG's platform routes

`PATCH`, deployment `PATCH` and `clusters`. OEG's platform routes

(`/platform/v1/...`: federation, operations, health) and its TMF facade have no tool either.



### K.2 Request Rules
@@ -190,7 +190,7 @@ These OEG CAMARA operations have no tool: QoD `extend` and `retrieve-sessions`, 
| Headers | `accept: application/json`; `content-type: application/json` on bodies |

| Correlator | Optional `xCorrelator` argument, sent as `x-correlator`. It must match `[a-zA-Z0-9-_:;./<>{}]{0,256}`, OEG's CAMARA alphabet, or the tool fails before calling |

| Body | Built from typed models; fields left empty are omitted. Inputs are checked before the call ([contract §3](/ai2/interface-contract.md)) |

| Idempotency | `instantiate_app`, `create_app_deployment` and `create_traffic_influence` send `Idempotency-Key` when the model supplies `idempotencyKey` (at most 128 characters). Other writes send none |

| Idempotency | `instantiate_app`, `create_app_deployment`, `create_traffic_influence` and `create_traffic_influence_device` send `Idempotency-Key` when the model supplies `idempotencyKey` (at most 128 characters). Other writes send none |

| Timeout | 15 seconds per OEG call. A tool never retries; the model may call it again |

| Redirects | Followed by the Edge Application Management tools only |

| Proxy | The HTTP client reads proxy settings from the environment (`HTTP_PROXY`, `HTTPS_PROXY`) |
@@ -337,7 +337,7 @@ AI² has no agreed retry rules; retrying a chat may repeat writes (overview F7). 
| Authentication, authorization, tenant isolation | The caller's token is passed on; OEG decides ([ADR-0048](/decisions/0048-platform-roles.md)). OEG scopes reads and deletes to the caller's app provider and hides other providers' resources with 404; AI² inherits that through the caller's token. Sharing within an organization remains open ([oeg/overview-and-architecture.md F5](/oeg/overview-and-architecture.md#f-open-questions)). AI² does not validate tokens (F1). Memory is not tied to the caller (F4) |

| Ownership, state transitions, invariants | AI² owns no platform resource. OEG and SRM own every lifecycle. AI²'s only state is session memory (§L). Invariant: AI² holds no OEG credentials (REQ-AI2-01); its only secret is the Groq API key |

| Transactions, concurrency, consistency | No transactions. Each tool call is a separate OEG call, so a failed run can leave some changes done (§J.3). Same-session requests are not coordinated (§L.3) |

| Idempotency, timeouts, retries, cancellation | Groq: 15 seconds per attempt, up to 3 retries. OEG: 15 seconds, no tool retries. Three tools can send `Idempotency-Key` (§K.2). Portal: 120 seconds. Cancellation and duplicate handling are open (F5, F7) |

| Idempotency, timeouts, retries, cancellation | Groq: 15 seconds per attempt, up to 3 retries. OEG: 15 seconds, no tool retries. Four tools can send `Idempotency-Key` (§K.2). Portal: 120 seconds. Cancellation and duplicate handling are open (F5, F7) |

| Event delivery, ordering, duplicates | Not applicable: AI² publishes and consumes no events. Callback URLs a user gives a tool are delivered by OEG, not AI² |

| Schema migration, backward compatibility | No database. The chat body is shared with the portal (REQ-AI2-04); change both together ([implementation §V.6](/ai2/implementation-and-delivery.md)). The chat API has no version; whether it needs one is unspecified. OEG API versions are fixed per tool (§K.1) |

| Data retention and deletion | Memory lives for `MEMORY_TTL_SECONDS` after its last use; there is no delete route. An agreed retention is open (F8) |