mirror of
https://github.com/OpenBMB/ChatDev.git
synced 2026-04-25 11:18:06 +00:00
112 lines
4.1 KiB
Markdown
Executable File
112 lines
4.1 KiB
Markdown
Executable File
# Config Schema API Contract
|
||
|
||
This reference explains how `/api/config/schema` and `/api/config/schema/validate` expose DevAll's dynamic config metadata so IDEs, frontend form builders, and CLI tools can scope schemas with breadcrumbs.
|
||
|
||
## 1. Endpoints
|
||
| Method & Path | Purpose |
|
||
| --- | --- |
|
||
| `POST /api/config/schema` | Returns the schema for a config node described by breadcrumbs. |
|
||
| `POST /api/config/schema/validate` | Validates a YAML/JSON document and optionally echoes the scoped schema. |
|
||
|
||
### 1.1 Request body (shared fields)
|
||
```json
|
||
{
|
||
"breadcrumbs": [
|
||
{"node": "DesignConfig", "field": "graph"},
|
||
{"node": "GraphConfig", "field": "nodes"},
|
||
{"node": "NodeConfig", "value": "model"}
|
||
]
|
||
}
|
||
```
|
||
- `node` (required): class name (`DesignConfig`, `GraphConfig`, `NodeConfig`, etc.) that must match the class reached so far.
|
||
- `field` (optional): child field to traverse. When omitted, the breadcrumb only asserts you remain on `node`.
|
||
- `value` (optional): use when the child class depends on a discriminator (e.g., node `type`). Supply the value as it would appear in YAML.
|
||
- `index` (optional int): reserved for list traversal; current configs rely on `value`/`field` for navigation.
|
||
|
||
### 1.2 `/schema` response
|
||
```json
|
||
{
|
||
"schemaVersion": "0.1.0",
|
||
"node": "NodeConfig",
|
||
"fields": [
|
||
{
|
||
"name": "id",
|
||
"typeHint": "str",
|
||
"required": true,
|
||
"description": "Unique node identifier"
|
||
},
|
||
{
|
||
"name": "type",
|
||
"typeHint": "str",
|
||
"required": true,
|
||
"enum": ["model", "python", "agent"],
|
||
"enumOptions": [
|
||
{"value": "model", "label": "LLM Node", "description": "Runs provider-backed models"}
|
||
]
|
||
}
|
||
],
|
||
"constraints": [...],
|
||
"breadcrumbs": [...],
|
||
"cacheKey": "f90d..."
|
||
}
|
||
```
|
||
- `fields`: serialized `ConfigFieldSpec` entries; nested targets include `childRoutes`.
|
||
- `constraints`: emitted from `collect_schema()` (mutual exclusivity, required combos, etc.).
|
||
- `cacheKey`: SHA-1 hash of `{node, breadcrumbs}` so clients can memoize responses.
|
||
|
||
### 1.3 `/schema/validate` payloads
|
||
Add `document` alongside breadcrumbs:
|
||
```json
|
||
{
|
||
"breadcrumbs": [{"node": "DesignConfig"}],
|
||
"document": """
|
||
name: demo
|
||
version: 0.4.0
|
||
workflow:
|
||
nodes: []
|
||
edges: []
|
||
"""
|
||
}
|
||
```
|
||
Responses:
|
||
- Valid document: `{ "valid": true, "schema": { ... } }`
|
||
- Config error:
|
||
```json
|
||
{
|
||
"valid": false,
|
||
"error": "field 'nodes' must not be empty",
|
||
"path": ["workflow", "nodes"],
|
||
"schema": { ... }
|
||
}
|
||
```
|
||
- Malformed YAML: HTTP 400 with `{ "message": "invalid_yaml", "error": "..." }`.
|
||
|
||
## 2. Breadcrumb Tips
|
||
- Begin with `{ "node": "DesignConfig" }`.
|
||
- Each hop’s `node` must match the current config class or the API returns HTTP 422.
|
||
- Use `field` to step into nested configs (graph → nodes → config, etc.).
|
||
- Use `value` for discriminator-based children (node `type`, tooling `type`, etc.).
|
||
- Non-navigable targets raise `field '<name>' on <node> is not navigable`.
|
||
|
||
## 3. CLI Helper
|
||
```bash
|
||
python run.py --inspect-schema --schema-breadcrumbs '[{"node":"DesignConfig","field":"graph"}]'
|
||
```
|
||
The CLI prints the same JSON as `/schema`, which is useful while editing `FIELD_SPECS` or debugging registries before exporting templates.
|
||
|
||
## 4. Frontend Pattern
|
||
1. Fetch base schema with `[{node: 'DesignConfig', field: 'graph'}]` to render the workflow form.
|
||
2. When users open nested modals (node config, tooling config, etc.), append breadcrumbs describing the path and refetch.
|
||
3. Cache responses using `cacheKey` + breadcrumbs.
|
||
4. Before saving, call `/schema/validate` to surface `error` + `path` inline.
|
||
|
||
## 5. Error Reference
|
||
| HTTP Code | Situation | Detail payload |
|
||
| --- | --- | --- |
|
||
| 400 | YAML parse failure | `{ "message": "invalid_yaml", "error": "..." }` |
|
||
| 422 | Breadcrumb resolution failure | `{ "message": "breadcrumb node 'X'..." }` |
|
||
| 200 + `valid=false` | Backend `ConfigError` | `{ "error": "...", "path": ["workflow", ...] }` |
|
||
| 200 + `valid=true` | Document OK | Schema echoed back for the requested breadcrumbs. |
|
||
|
||
Pair this contract with `FIELD_SPECS` to build schema-aware experiences without hardcoding config structures.
|