docs: Update documentation for AtomizerSpec v2.0 unified configuration
Phase 4 documentation updates: - CANVAS.md: Add AtomizerSpec v2.0 schema, custom extractors section, spec REST API endpoints, and updated file structure - DASHBOARD.md: Add V3.1 release notes, AtomizerSpec API endpoints, and unified configuration features - CLAUDE.md: Add complete AtomizerSpec v2.0 section with code examples, MCP tools reference, API endpoints, and updated directory structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
166
CLAUDE.md
166
CLAUDE.md
@@ -22,10 +22,12 @@ On **EVERY new Claude session**, perform these initialization steps:
|
||||
|
||||
### Step 2: Detect Study Context
|
||||
If working directory is inside a study (`studies/*/`):
|
||||
1. Read `optimization_config.json` to understand the study
|
||||
2. Check `2_results/study.db` for optimization status (trial count, state)
|
||||
1. Read `atomizer_spec.json` (v2.0) or `optimization_config.json` (legacy) to understand the study
|
||||
2. Check `3_results/study.db` for optimization status (trial count, state)
|
||||
3. Summarize study state to user in first response
|
||||
|
||||
**Note**: As of January 2026, all studies use **AtomizerSpec v2.0** (`atomizer_spec.json`). Legacy `optimization_config.json` files are automatically migrated.
|
||||
|
||||
### Step 3: Route by User Intent
|
||||
|
||||
**CRITICAL: Actually READ the protocol file before executing the task. Don't work from memory.**
|
||||
@@ -167,23 +169,38 @@ Atomizer/
|
||||
│ ├── core/ # Optimization runners, method_selector, gradient_optimizer
|
||||
│ ├── nx/ # NX/Nastran integration (solver, updater, session_manager)
|
||||
│ ├── study/ # Study management (creator, wizard, state, reset)
|
||||
│ ├── config/ # Configuration (manager, builder, setup_wizard)
|
||||
│ ├── config/ # Configuration (v2.0)
|
||||
│ │ ├── spec_models.py # Pydantic models for AtomizerSpec
|
||||
│ │ ├── spec_validator.py # Semantic validation
|
||||
│ │ └── migrator.py # Legacy config migration
|
||||
│ ├── schemas/ # JSON Schema definitions
|
||||
│ │ └── atomizer_spec_v2.json # AtomizerSpec v2.0 schema
|
||||
│ ├── reporting/ # Reports (visualizer, markdown_report, landscape_analyzer)
|
||||
│ ├── processors/ # Data processing
|
||||
│ │ └── surrogates/ # Neural network surrogates
|
||||
│ ├── extractors/ # Physics extraction library (unchanged)
|
||||
│ ├── extractors/ # Physics extraction library
|
||||
│ │ └── custom_extractor_loader.py # Runtime custom function loader
|
||||
│ ├── gnn/ # GNN surrogate module (Zernike)
|
||||
│ ├── utils/ # Utilities (dashboard_db, trial_manager, study_archiver)
|
||||
│ └── validators/ # Validation (unchanged)
|
||||
├── studies/ # User studies
|
||||
├── tools/ # CLI tools (archive_study.bat, zernike_html_generator.py)
|
||||
├── archive/ # Deprecated code (for reference)
|
||||
└── atomizer-dashboard/ # React dashboard (V3.0)
|
||||
└── atomizer-dashboard/ # React dashboard (V3.1)
|
||||
├── frontend/ # React + Vite + Tailwind
|
||||
│ └── src/components/canvas/ # Canvas Builder with 8 node types
|
||||
│ └── src/
|
||||
│ ├── components/canvas/ # Canvas Builder with 9 node types
|
||||
│ ├── hooks/useSpecStore.ts # AtomizerSpec state management
|
||||
│ ├── lib/spec/converter.ts # Spec ↔ ReactFlow converter
|
||||
│ └── types/atomizer-spec.ts # TypeScript types
|
||||
└── backend/api/ # FastAPI + SQLite
|
||||
├── services/ # claude_agent, nx_introspection, session_manager
|
||||
└── routes/ # files, nx, terminal, optimization
|
||||
├── services/
|
||||
│ ├── spec_manager.py # SpecManager service
|
||||
│ ├── claude_agent.py # Claude API integration
|
||||
│ └── context_builder.py # Context assembly
|
||||
└── routes/
|
||||
├── spec.py # AtomizerSpec REST API
|
||||
└── optimization.py # Optimization endpoints
|
||||
```
|
||||
|
||||
### Dashboard Quick Reference
|
||||
@@ -194,11 +211,142 @@ Atomizer/
|
||||
| **Dashboard Overview** | `docs/04_USER_GUIDES/DASHBOARD.md` |
|
||||
| **Implementation Status** | `docs/04_USER_GUIDES/DASHBOARD_IMPLEMENTATION_STATUS.md` |
|
||||
|
||||
**Canvas V3 Features:**
|
||||
**Canvas V3.1 Features (AtomizerSpec v2.0):**
|
||||
- **AtomizerSpec v2.0**: Unified JSON configuration format
|
||||
- File browser for model selection
|
||||
- Model introspection (expressions, solver type, dependencies)
|
||||
- One-click add expressions as design variables
|
||||
- Claude chat integration with WebSocket
|
||||
- Custom extractors with in-canvas code editor
|
||||
- Real-time WebSocket synchronization
|
||||
|
||||
## AtomizerSpec v2.0 (Unified Configuration)
|
||||
|
||||
**As of January 2026**, all Atomizer studies use **AtomizerSpec v2.0** as the unified configuration format.
|
||||
|
||||
### Key Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| **Single Source of Truth** | One `atomizer_spec.json` file defines everything |
|
||||
| **Schema Version** | `"version": "2.0"` in the `meta` section |
|
||||
| **Node IDs** | All elements have unique IDs (`dv_001`, `ext_001`, `obj_001`) |
|
||||
| **Canvas Layout** | Node positions stored in `canvas_position` fields |
|
||||
| **Custom Extractors** | Python code can be embedded in the spec |
|
||||
|
||||
### File Location
|
||||
|
||||
```
|
||||
studies/{study_name}/
|
||||
├── atomizer_spec.json # ← AtomizerSpec v2.0 (primary)
|
||||
├── optimization_config.json # ← Legacy format (deprecated)
|
||||
└── 3_results/study.db # ← Optuna database
|
||||
```
|
||||
|
||||
### Working with Specs
|
||||
|
||||
#### Reading a Spec
|
||||
```python
|
||||
from optimization_engine.config.spec_models import AtomizerSpec
|
||||
import json
|
||||
|
||||
with open("atomizer_spec.json") as f:
|
||||
spec = AtomizerSpec.model_validate(json.load(f))
|
||||
|
||||
print(spec.meta.study_name)
|
||||
print(spec.design_variables[0].bounds.min)
|
||||
```
|
||||
|
||||
#### Validating a Spec
|
||||
```python
|
||||
from optimization_engine.config.spec_validator import SpecValidator
|
||||
|
||||
validator = SpecValidator()
|
||||
report = validator.validate(spec_dict, strict=False)
|
||||
if not report.valid:
|
||||
for error in report.errors:
|
||||
print(f"Error: {error.path} - {error.message}")
|
||||
```
|
||||
|
||||
#### Migrating Legacy Configs
|
||||
```python
|
||||
from optimization_engine.config.migrator import SpecMigrator
|
||||
|
||||
migrator = SpecMigrator(study_dir)
|
||||
spec = migrator.migrate_file(
|
||||
study_dir / "optimization_config.json",
|
||||
study_dir / "atomizer_spec.json"
|
||||
)
|
||||
```
|
||||
|
||||
### Spec Structure Overview
|
||||
|
||||
```json
|
||||
{
|
||||
"meta": {
|
||||
"version": "2.0",
|
||||
"study_name": "bracket_optimization",
|
||||
"created_by": "canvas", // "canvas", "claude", "api", "migration", "manual"
|
||||
"modified_by": "claude"
|
||||
},
|
||||
"model": {
|
||||
"sim": { "path": "model.sim", "solver": "nastran" }
|
||||
},
|
||||
"design_variables": [
|
||||
{
|
||||
"id": "dv_001",
|
||||
"name": "thickness",
|
||||
"expression_name": "web_thickness",
|
||||
"type": "continuous",
|
||||
"bounds": { "min": 2.0, "max": 10.0 },
|
||||
"baseline": 5.0,
|
||||
"enabled": true,
|
||||
"canvas_position": { "x": 50, "y": 100 }
|
||||
}
|
||||
],
|
||||
"extractors": [...],
|
||||
"objectives": [...],
|
||||
"constraints": [...],
|
||||
"optimization": {
|
||||
"algorithm": { "type": "TPE" },
|
||||
"budget": { "max_trials": 100 }
|
||||
},
|
||||
"canvas": {
|
||||
"edges": [
|
||||
{ "source": "dv_001", "target": "model" },
|
||||
...
|
||||
],
|
||||
"layout_version": "2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Spec Tools
|
||||
|
||||
Claude can modify specs via MCP tools:
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `canvas_add_node` | Add design variable, extractor, objective, constraint |
|
||||
| `canvas_update_node` | Update node properties (bounds, weights, etc.) |
|
||||
| `canvas_remove_node` | Remove node and clean up edges |
|
||||
| `canvas_connect_nodes` | Add edge between nodes |
|
||||
| `validate_canvas_intent` | Validate entire spec |
|
||||
| `execute_canvas_intent` | Create study from canvas |
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
|----------|--------|---------|
|
||||
| `/api/studies/{id}/spec` | GET | Retrieve full spec |
|
||||
| `/api/studies/{id}/spec` | PUT | Replace entire spec |
|
||||
| `/api/studies/{id}/spec` | PATCH | Update specific fields |
|
||||
| `/api/studies/{id}/spec/validate` | POST | Validate and get report |
|
||||
| `/api/studies/{id}/spec/nodes` | POST | Add new node |
|
||||
| `/api/studies/{id}/spec/nodes/{id}` | PATCH | Update node |
|
||||
| `/api/studies/{id}/spec/nodes/{id}` | DELETE | Remove node |
|
||||
|
||||
**Full documentation**: `docs/plans/UNIFIED_CONFIGURATION_ARCHITECTURE.md`
|
||||
|
||||
### Import Migration (v2.0)
|
||||
Old imports still work with deprecation warnings. New paths:
|
||||
|
||||
Reference in New Issue
Block a user