# Process V2

`v2` is the current default orchestration process for agent requests.

It is designed as a small stage-based pipeline:

1. accept request
2. route intent
3. run intent-specific workflow
4. publish final user response

The process definition lives in [process.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/process.py).

## Step Map

### 1. Bootstrap

File:
[bootstrap_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v1/steps/bootstrap_step.py)

Responsibility:
- announce request acceptance
- announce selected process version
- initialize trace logging

SSE source:
- `orchestrator`

### 2. Intent Router

File:
[route_intent_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/route_intent_step.py)

Responsibility:
- build task runtime context
- enrich request context
- call `IntentRouterV2`
- persist `route_result` into orchestration context

SSE source:
- `intent_router`

Main status messages:
- request is being routed
- final `intent / sub_intent`

### 3. Workflow Execution

Base behavior:
[workflow_step_base.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/workflow_step_base.py)

Intent-specific steps:
- [execute_documentation_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_documentation_workflow_step.py)
- [execute_openapi_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_openapi_workflow_step.py)
- [execute_general_qa_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_general_qa_workflow_step.py)
- [execute_fallback_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_fallback_workflow_step.py)

Responsibility:
- choose workflow by `route_result.intent`
- run the selected workflow
- expose workflow diagnostics through SSE
- store workflow result in orchestration context

Workflow mapping:

| Intent | Workflow class | Notes |
|---|---|---|
| `DOCUMENTATION_EXPLAIN` | `DocsQaWorkflow` | docs explanation pipeline |
| `OPENAPI_GENERATION` | `OpenApiWorkflow` | OpenAPI generation from docs evidence |
| `GENERAL_QA` | `GeneralQaWorkflow` | general docs-oriented QA |
| any other intent | `FallbackWorkflow` | safety fallback |

Published SSE stages:
- `task_workflow`
- `rag_retrieval`
- `evidence_gate`
- `workflow_result`

### 4. Finalize

File:
[finalize_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v1/steps/finalize_step.py)

Responsibility:
- publish final `user` event with answer text
- publish terminal status message
- let facade mark request as `done`

SSE sources:
- `agent`
- `orchestrator`

## Intent Routing

Router adapter:
[intent_router_adapter.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/adapters/intent_router_adapter.py)

Underlying implementation:
[router.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/intent_router_v2/router.py)

The router decides:
- `intent`
- `sub_intent`
- retrieval profile
- retrieval layers and constraints
- evidence policy

For docs-oriented requests the main active intents are:
- `DOCUMENTATION_EXPLAIN`
- `OPENAPI_GENERATION`
- `GENERAL_QA`

## Retrieval And Evidence Gate

`v2` does not implement retrieval itself inside orchestration.

Instead it delegates execution to workflow classes that internally use the existing docs pipeline:

- [docs_qa.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/task_runtime/workflows/docs_qa.py)
- [openapi.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/task_runtime/workflows/openapi.py)
- [general_qa.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/task_runtime/workflows/general_qa.py)

These workflows currently rely on:
- `DocsQAPipelineRunner`
- docs retrieval planning
- docs evidence builder
- docs gate logic

Important:
- docs retrieval and gate logic still live in the existing docs runtime layer
- orchestration `v2` only makes those stages explicit at transport/process level

## SSE Contract In V2

Client-visible message categories:
- `status`
- `user`
- `system`

Currently used in `v2`:

- `status` from `orchestrator`
- `status` from `intent_router`
- `status` from `task_workflow`
- `status` from `rag_retrieval`
- `status` from `evidence_gate`
- `status` from `workflow_result`
- `user` from `agent`

Typical sequence:

1. request accepted
2. process `v2` started
3. routing started
4. route selected
5. workflow started
6. retrieval diagnostics
7. evidence gate diagnostics
8. workflow result summary
9. final user answer
10. processing completed

## Trace Logging

Per-request trace files are written by:
[request_trace_logger.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/api/infrastructure/logging/request_trace_logger.py)

Location:
[runtime_traces/agent_requests](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/runtime_traces/agent_requests)

Each request trace contains:
- request metadata
- user message
- process steps
- emitted events
- final result or error

## Extension Points

Recommended next extensions:

1. add a dedicated workflow step for `GENERATE_DOCS_FROM_CODE`
2. move docs gate diagnostics into strongly typed orchestration payloads
3. split workflow execution into smaller orchestration stages:
   - retrieval
   - evidence assembly
   - gate
   - answer generation
4. add session-level trace aggregation in addition to request-level logs
