# OSS Coordinator

Python inputs, results, permissions and executable examples for oss coordinator.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/python/tour.md) and [Python types](https://beepgrid.com/docs/sdks/python/types.md). The example at the end runs after the tour setup.

## assistance

Read OSS Coordinator enablement and provider configuration status.

```text
assistance(self)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |


**Returns:** AssistanceSettings: overseer, version, overseer_configured.

**Permissions, lifecycle and errors:** Provider configured and workspace enabled are separate states. The wire name overseer is retained for SDK/API compatibility; the product calls it Coordinator.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## update_assistance

Enable or disable Coordinator through the public API, without the UI.

```text
update_assistance(self, *, overseer: bool | None=None, version: int | None=None)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `overseer` | `bool \| None` (default None) | Whether OSS Coordinator is enabled in this workspace. The wire name is retained for compatibility. |
| `version` | `int \| None` (default None) | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

**Returns:** Current AssistanceSettings after the update.

**Permissions, lifecycle and errors:** A person needs manage assistance:workspace. Configure a provider on the engine first. Use version to reject stale updates; disabling invalidates unconfirmed plans.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## plan_overseer

Prepare a reviewable Coordinator plan using the caller's authorized specialist context.

```text
plan_overseer(self, prompt: str, target: dict[str, str] | None=None, *, previous_plan_id: str | None=None, key: str | None=None)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `prompt` | `str` (required) | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `target` | `dict[str, str] \| None` (default None) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `previous_plan_id` | `str \| None` (default None) | Optional prior plan belonging to the caller for continuing permitted context. |
| `key` | `str \| None` (default None) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |

**Returns:** OverseerPlan with operation, sources, selected agents, instructions, expiry and requires_confirmation.

**Permissions, lifecycle and errors:** Does not automatically dispatch the plan. Model failures send no instructions. Retain the key for a transport-unknown result; optional target narrows scope and previous_plan_id supplies permitted prior context.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## overseer_plans

List Coordinator plans visible to the current person.

```text
overseer_plans(self)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |


**Returns:** Array of OverseerPlan.

**Permissions, lifecycle and errors:** Another person's plans are not implicitly shared. Plans do not grant permission; current access is rechecked on use.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## overseer_plan

Read one Coordinator plan and its current dispatch/reply state.

```text
overseer_plan(self, plan_id: str)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `plan_id` | `str` (required) | Saved Coordinator plan ID returned by plan_overseer or coordinate. |

**Returns:** OverseerPlan, with dispatches, replies and any reply_summary.

**Permissions, lifecycle and errors:** A returned request may still be open. Do not present an instruction's acceptance as finished specialist work.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## confirm_overseer

Dispatch a still-valid reviewed plan.

```text
confirm_overseer(self, plan_id: str)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `plan_id` | `str` (required) | Saved Coordinator plan ID returned by plan_overseer or coordinate. |

**Returns:** OverseerPlan containing attributed dispatches.

**Permissions, lifecycle and errors:** Uses only the saved server plan ID. Rechecks current permissions, scope, enablement and expiry. Repeating confirmation reuses that plan's dispatch, not a new arbitrary model command.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## summarize_overseer

Ask the configured model to summarize currently authorized specialist replies.

```text
summarize_overseer(self, plan_id: str)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `plan_id` | `str` (required) | Saved Coordinator plan ID returned by plan_overseer or coordinate. |

**Returns:** Updated OverseerPlan with reply_summary, replies, digest or summary_error.

**Permissions, lifecycle and errors:** Pending and missing replies must stay explicit. Summary is not an action or independent factual verification. Provider billing and the per-person rate limit apply.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## coordinate

Let Coordinator choose specialists and dispatch permitted communication automatically.

```text
coordinate(self, prompt: str, *, key: str | None=None, **options: Any)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `prompt` | `str` (required) | Instruction to Coordinator. The engine supplies only currently permitted specialist context. |
| `key` | `str \| None` (default None) | Saved idempotency key. Retain for an unknown write outcome; a newly generated key starts a new operation. |
| `**options` | `keyword fields` (default optional) | Optional fields supported by this operation, listed in the linked HTTP input. Unknown fields are not a supported extension mechanism. |

**Returns:** OverseerPlan marked automatic, with attributed instructions/dispatches or a status answer.

**Permissions, lifecycle and errors:** No UI preview is required. Uses the caller's current rights, not an operator override. It cannot approve business actions, change identities or grant permissions. Model execution is billed by the configured provider.

[Working Python example](https://beepgrid.com/docs/sdks/python/coordinator/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/python/tour.md). Assertions check the returned data; the full tour is a runnable program.



```python
settings = owner.assistance()
assert settings['overseer_configured'], 'Configure BEEPGRID_AI_PROVIDER and BEEPGRID_AI_MODEL on the engine first'
owner.update_assistance(overseer=True, version=settings['version'])
plan = owner.plan_overseer('Ask the available specialists whether staging is ready.')
assert owner.overseer_plan(plan['id'])['id'] == plan['id']
assert any(item['id'] == plan['id'] for item in owner.overseer_plans())
confirmed = owner.confirm_overseer(plan['id'])
assert confirmed['id'] == plan['id']
time.sleep(1.1)  # Assistance has a per-person rate limit.
summary = owner.summarize_overseer(plan['id'])
assert summary['id'] == plan['id']
time.sleep(1.1)
automatic = owner.coordinate('Ask the specialists to report any release blockers.', key=run_id + '/coordinate')
assert automatic['id']
```