Skip to main content

Typed scenario invocation

Invoke a CodeGraph analysis scenario through the exported role-bound Python request contract. See the examples and checks before applying it.

User Guides

CodeGraph exports one typed Python request surface for role-bound scenario execution. Use it for an in-process integration that already participates in a governed CodeGraph task. For an agent or remote client, prefer the registered MCP/API surface for that client instead of importing repository internals.

Minimal request

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Update the interface documentation for the selected task.",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["source://current-contract"],
    },
    employee_id="codegraph_docs",
    scenario_id="scenario_03",
    event_type="docs_memory_sync_start",
    execution_source="customer_in_process_integration",
)

result = invoke_role_bound_scenario_request(request)

The example is intentionally bound to the documentation employee and scenario. Choose another scenario only when its employee policy and task carrier allow it.

Required governance context

The request object validates three scope fields in context:

  • project_key identifies the registered CodeGraph project;
  • namespace identifies its namespace;
  • task_id binds the work to the active task capsule.

An empty scope fails closed with role_bound_scenario_contract_missing:<fields>. The runtime also resolves or validates the accountable employee_id, verifies that the employee may run the selected scenario, builds invocation evidence and runs the scenario preflight. Those checks can reject a syntactically valid request.

Do not catch a governance error and retry through a lower-level handler. Repair the missing carrier, policy, event or evidence condition.

Request fields

Request fields
Field Purpose
query User intent passed to the selected workflow.
context Project, task and optional evidence context.
employee_id Accountable digital employee. It must be allowed for the scenario.
scenario_id Canonical scenario such as scenario_03.
event_type Governed event for the employee lane. When omitted, the runtime selects that employee’s default event.
execution_source Stable identifier for the integrating surface.

If scenario_id is omitted, the runtime classifies the query. Explicit IDs are usually better for reproducible automation because they preserve the intended lane and make policy failures easier to diagnose.

Result contract

The return value is a dictionary produced by the selected scenario. Shared fields added by the role-bound wrapper include:

  • scenario_id: canonical selected scenario;
  • intent: intent mapped from that scenario;
  • classification_method: selection method;
  • metadata.role_bound_scenario_invocation: employee, event, execution source, workflow, evidence reference and preflight status;
  • metadata.scenario_invocation_evidence: the full invocation evidence object.

Scenario-specific fields can differ. Check for the shared envelope first, then validate the fields required by the selected scenario. Do not assume an undocumented answer, sources or confidence shape across every workflow.

Error handling

Treat stable prefixes as categories and preserve their complete message in diagnostics:

  • role_bound_scenario_contract_missing — required task scope is absent;
  • role_bound_scenario_preflight_failed — evidence or event preflight is not ready;
  • role_bound_employee_not_allowed_for_scenario — employee/scenario policy mismatch;
  • role_bound_scenario_retired — the requested scenario cannot execute;
  • role_bound_scenario_not_registered — no workflow handler is registered.

Example boundary handling:

try:
    result = invoke_role_bound_scenario_request(request)
except RuntimeError as exc:
    if str(exc).startswith("role_bound_"):
        raise IntegrationError(f"CodeGraph scenario rejected: {exc}") from exc
    raise

Keep the selected scenario, story, employee and evidence lane together; they define the operation’s meaning.

Concurrency and side effects

Invocation is synchronous from the caller’s perspective. The selected workflow may query project services or produce governed evidence. Run it outside an async event loop’s main thread when it can block, and use the orchestration surface appropriate to the deployment when durable remote execution is needed.

The typed request covers the declared scenario operation. File edits, publication and state changes run through the task carrier, lane ownership and approval defined by their own contracts.

Maintained sources

  • src/digital_employees/runtime/scenarios/__init__.py defines the exported names.
  • src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py defines request validation, routing and the shared result envelope.
  • src/digital_employees/runtime/scenarios/employee_scenario_invocation.py defines employee/scenario/event policy and invocation evidence.

When the installed source differs from this guide, the exported source contract is authoritative.

Report a documentation issue