docs(guides): fix vendor_capabilities.py, mma_exec.py, audit_optional_returns drift
- Readme.md AI Client row: '5 providers' -> 8; added VendorCapabilities inlining note + Result[str] send() API note. - guide_ai_client.md: src/vendor_capabilities.py refs -> src/ai_client.py #region: Vendor Capabilities (2 sites: the capabilities param comment + the V2 Capability Matrix section). - docs/AGENTS.md: audit_optional_returns.py -> audit_optional_in_3_files.py (the live script; the successor is not yet built). - guide_mma.md SubConversationRunner sketch: 'Reuses mma_exec.py' -> 'Would reuse the WorkerPool internal subprocess template (NOT the deprecated mma_exec.py)'. - guide_multi_agent_conductor.md: architecture diagram box 'Workers call mma_exec.py' -> 'Workers run via the internal subprocess template (run_worker_lifecycle; NOT the deprecated meta-tooling mma_exec.py)'; the mma_exec.py box relabeled to run_worker_lifecycle; See Also 'scripts/mma_exec.py — sub-agent entry point' -> 'src/multi_agent_conductor.py:run_worker_lifecycle (NOT the deprecated meta-tooling mma_exec.py)'.
This commit is contained in:
+2
-2
@@ -34,7 +34,7 @@ The canonical mandate is in [`conductor/code_styleguides/data_oriented_design.md
|
||||
|
||||
4. **The enforcement audit scripts** — the project-level enforcement set:
|
||||
- `scripts/audit_weak_types.py --strict` — flags `dict[str, Any]`, `Any`, anonymous tuples
|
||||
- `scripts/audit_optional_returns.py --strict` — flags `Optional[T]` return types in ALL `src/*.py` (post-2026-06-27 successor to `audit_optional_in_3_files.py`)
|
||||
- `scripts/audit_optional_in_3_files.py --strict` — flags `Optional[T]` return types in the 4 baseline refactored files (`src/mcp_client.py`, `src/ai_client.py`, `src/rag_engine.py`, plus one more). An all-`src/*.py` successor (`audit_optional_returns.py`) is referenced in older planning docs but is NOT yet built — the live script today is `audit_optional_in_3_files.py`.
|
||||
- `scripts/audit_exception_handling.py --strict` — the data-oriented error handling convention
|
||||
- `scripts/audit_main_thread_imports.py` — always strict; the import graph gate
|
||||
- `scripts/audit_no_models_config_io.py` — the config-I/O ownership gate
|
||||
@@ -45,7 +45,7 @@ The canonical mandate is in [`conductor/code_styleguides/data_oriented_design.md
|
||||
```bash
|
||||
# Run before claiming "done"
|
||||
uv run python scripts/audit_weak_types.py
|
||||
uv run python scripts/audit_optional_returns.py
|
||||
uv run python scripts/audit_optional_in_3_files.py
|
||||
uv run python scripts/audit_exception_handling.py
|
||||
uv run python scripts/audit_main_thread_imports.py
|
||||
uv run python scripts/audit_no_models_config_io.py
|
||||
|
||||
+1
-1
@@ -31,7 +31,7 @@ This documentation suite provides comprehensive technical reference for the Manu
|
||||
| [Testing](guide_testing.md) | 322 test files, 5 test categories (unit, integration, live_gui, perf, simulation), 7 conftest fixtures (`isolate_workspace`, `reset_paths`, `reset_ai_client`, `vlogger`, `kill_process_tree`, `mock_app`, `live_gui` session-scoped), Hook API testing pattern, Puppeteer pattern for MMA simulation, mock provider strategy, opt-in clean install test, opt-in docker test, coverage targets, anti-patterns (no arbitrary core mocking, artifact isolation to `tests/artifacts/`), early-render C-level crash pattern (`_ini_capture_ready` defer-not-catch for `imgui.save_ini_settings_to_memory`), live_gui authoring contract (wait-for-ready pattern over `time.sleep`, narrow test paths over kitchen-sink `render_main_interface` mocks), test-ordering sensitivity (session-scoped fixture) |
|
||||
| [Themes](guide_themes.md) | TOML-based theming system: file layout (`themes/<name>.toml` global + `project_themes.toml` per-project), schema (`syntax_palette` + `[colors]` table with `imgui.Col_` snake_case keys), 4-syntax-palette upstream limit (`imgui-bundle` ships `dark`/`light`/`mariana`/`retro_blue` only), built-in vs TOML palette dispatch, `load_themes_from_disk` / `get_syntax_palette_for_theme` / `apply_syntax_palette` public API, hot-reload behavior, color-callable convention (`C_LBL()` / `C_VAL()` for theme-aware helpers) |
|
||||
| [GUI Main](guide_gui_2.md) | `src/gui_2.py` reference: App class lifecycle, ~90 module-level render functions (UI Delegation Pattern), immgui immediate-mode rendering, Multi-Viewport docks, panel registry, command palette integration, ImGuiScope context managers, hot reload support, key bindings (Ctrl+Shift+P, Ctrl+Alt+R, Ctrl+Z/Y), `_capture_workspace_profile` defer-not-catch pattern (line 813-841, `_ini_capture_ready` flag for `imgui.save_ini_settings_to_memory`), theme color-callable pattern (e.g. `DIR_COLORS`/`KIND_COLORS` dicts store `C_VAL` not `C_VAL()` and are called at use site), `__getattr__` ui_ attrs hasattr-guard (bcdc26d0 silent-None fix), `_LazyModule` / `_FiledialogStub` lazy import proxies, `startup_profiler` + `render_warmup_status_indicator` integration, native `_detect_refresh_rate_win32` (ctypes.EnumDisplaySettingsW) |
|
||||
| [AI Client](guide_ai_client.md) | `src/ai_client.py` reference: multi-provider LLM singleton (5 providers: Gemini, Anthropic, DeepSeek, MiniMax, Gemini CLI), async dispatch with `asyncio.gather`, threading.local for source tier tagging, context caching (Anthropic ephemeral + Gemini explicit), system prompt assembly, error interception for Tier 4 QA |
|
||||
| [AI Client](guide_ai_client.md) | `src/ai_client.py` reference: multi-provider LLM singleton (8 providers: gemini, anthropic, gemini_cli, deepseek, minimax, qwen, grok, llama), async dispatch with `asyncio.gather`, threading.local for source tier tagging, context caching (Anthropic ephemeral + Gemini explicit), system prompt assembly, error interception for Tier 4 QA, inlined `VendorCapabilities` registry (moved from the deleted `src/vendor_capabilities.py`), `Result[str]`-returning `send()` public API |
|
||||
| [API Hooks](guide_api_hooks.md) | `src/api_hooks.py` + `src/api_hook_client.py` reference: HookServer on `127.0.0.1:8999`, ApiHookClient Python wrapper, 8+ endpoints (`/status`, `/api/gui`, `/api/ask`, `/api/gui/mma_status`, `/api/performance`, `/api/comms`, `/api/diagnostics`), Remote Confirmation Protocol via `/api/ask` (synchronous blocking HITL), `custom_callback` action for invoking any registered App method |
|
||||
| [MCP Client](guide_mcp_client.md) | `src/mcp_client.py` reference: 45 native tools (File I/O, Python AST, C/C++ AST, Analysis, Network, Runtime, Beads), 3-layer security model (Allowlist Construction, Path Validation, Resolution Gate), `dispatch()`/`async_dispatch()` entry points, ExternalMCPManager for external MCP servers (Stdio + SSE), JSON-RPC 2.0 engine, public API, configuration |
|
||||
| [App Controller](guide_app_controller.md) | `src/app_controller.py` reference: headless orchestrator owning AppState and all subsystem managers (PresetManager, PersonaManager, ContextPresetManager, ToolPresetManager, ToolBiasEngine, RAGEngine, HistoryManager, WorkspaceManager, HookServer, HotReloader, PathManager), `_predefined_callbacks` and `_gettable_fields` registries for Hook API, SyncEventQueue bridge, preset/persona/context coordination, headless mode |
|
||||
|
||||
@@ -559,7 +559,7 @@ class OpenAICompatibleRequest:
|
||||
def send_openai_compatible(
|
||||
client: Any, # openai.OpenAI client with vendor-specific base_url + auth
|
||||
request: OpenAICompatibleRequest,
|
||||
*, capabilities: "VendorCapabilities", # from src/vendor_capabilities.py
|
||||
*, capabilities: "VendorCapabilities", # from src/ai_client.py #region: Vendor Capabilities
|
||||
) -> NormalizedResponse:
|
||||
```
|
||||
|
||||
@@ -664,7 +664,7 @@ For OpenRouter, custom URLs, and other cloud Llama endpoints, the existing OpenA
|
||||
|
||||
### V2 Capability Matrix (Phase 4)
|
||||
|
||||
Added 2026-06-11. The `VendorCapabilities` dataclass in `src/vendor_capabilities.py` now has 12 v2 fields beyond the original 7 v1 fields:
|
||||
Added 2026-06-11. The `VendorCapabilities` dataclass (now inlined in `src/ai_client.py` `#region: Vendor Capabilities`; moved from the deleted `src/vendor_capabilities.py` per `module_taxonomy_refactor_20260627` Phase 2.1) has 12 v2 fields beyond the original 7 v1 fields:
|
||||
|
||||
**V1 fields** (unchanged):
|
||||
- `vision`, `tool_calling`, `caching`, `streaming`, `model_discovery`, `context_window`, `cost_tracking`
|
||||
|
||||
+3
-1
@@ -634,7 +634,9 @@ class SubConversationResult:
|
||||
|
||||
class SubConversationRunner:
|
||||
async def spawn(self, prompt: str, *, allowed_tools: list[str] = None, ...) -> SubConversationResult:
|
||||
# Reuses mma_exec.py as the subprocess template
|
||||
# Would reuse the WorkerPool's internal subprocess template (NOT the
|
||||
# deprecated mma_exec.py — see docs/guide_meta_boundary.md for the
|
||||
# meta-tooling vs application domain distinction).
|
||||
# Returns the child's <nagent-response> content + token usage
|
||||
...
|
||||
```
|
||||
|
||||
@@ -35,12 +35,14 @@ Together they implement a **non-blocking execution engine** with thread-safe sta
|
||||
│ WorkerPool │
|
||||
│ - Configurable concurrency (default 4) │
|
||||
│ - Threads pull ready tickets, spawn workers │
|
||||
│ - Workers call mma_exec.py with sub-prompt │
|
||||
│ - Workers run via the internal subprocess │
|
||||
│ template (run_worker_lifecycle; NOT the │
|
||||
│ deprecated meta-tooling mma_exec.py) │
|
||||
└─────────────────┬───────────────────────────────┘
|
||||
│ per ticket
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ mma_exec.py (tier3-worker / tier4-qa) │
|
||||
│ run_worker_lifecycle (tier3-worker / tier4-qa) │
|
||||
│ - Stateless Tier 3 or Tier 4 sub-agent │
|
||||
│ - TDD cycle: red → green → refactor │
|
||||
│ - Commits per task │
|
||||
@@ -457,7 +459,7 @@ Tests use `unittest.mock.patch` to mock `subprocess.Popen` and `ai_client.send`
|
||||
- **[guide_architecture.md](guide_architecture.md)** — Threading model
|
||||
- **[guide_mma.md](guide_mma.md)** — MMA concepts (4-Tier hierarchy, Token Firewall)
|
||||
- **[guide_app_controller.md](guide_app_controller.md)** — How the conductor is owned by the controller
|
||||
- **[guide_models.md](guide_models.md)** — `Ticket` and `Track` data structures
|
||||
- **`scripts/mma_exec.py`** — The sub-agent entry point
|
||||
- **[guide_models.md](guide_models.md)** — `Ticket` and `Track` data structures (now in `src/mma.py`; moved out of `src/models.py`)
|
||||
- **`src/multi_agent_conductor.py:run_worker_lifecycle`** — The WorkerPool's internal subprocess template (the application-domain worker entry point; NOT the deprecated meta-tooling `scripts/mma_exec.py` — see `docs/guide_meta_boundary.md`)
|
||||
- **`scripts/mma.ps1`** — PowerShell wrapper
|
||||
- **`conductor/workflow.md`**](../conductor/workflow.md) — Track execution protocol
|
||||
|
||||
Reference in New Issue
Block a user