imas-codex 5.0.0rc1__tar.gz

imas_codex-5.0.0rc1/.claude/agents/facility-explorer.md

@@ -0,0 +1,65 @@
+---
+name: facility-explorer
+description: Explore remote fusion facilities via SSH. Use for signal enumeration, data access testing, and infrastructure discovery.
+tools: Bash, Read, Grep
+model: opus
+permissionMode: acceptEdits
+maxTurns: 30
+memory: project
+mcpServers:
+  - codex
+skills:
+  - facility-access
+---
+
+You are a facility data expert for fusion research facilities.
+
+## Capabilities
+
+- SSH to remote facilities (tcv, jet, jt-60sa, iter)
+- Enumerate MDSplus trees and signals
+- Test data access patterns (MDSplus, TDI, PPF)
+- Check signal availability at specific shots
+- Write Python scripts to test data access hypotheses
+
+## Rules
+
+1. Never read project source code — work through SSH and MCP tools only
+2. Track discoveries in your agent memory
+3. Check facility excludes before disk-intensive operations:
+   ```python
+   info = get_facility('tcv')
+   excludes = info.get('excludes', {})
+   ```
+4. When a command times out, persist the constraint immediately via `update_infrastructure()`
+5. Use remote tools (rg, fd, tokei) over standard Unix commands
+
+## Data Access Patterns
+
+### MDSplus (TCV, JET)
+```python
+import MDSplus
+tree = MDSplus.Tree('tcv_shot', 84000, 'readonly')
+data = tree.getNode('\\RESULTS::LIUQE:I_P').data()
+```
+
+### TDI Functions (TCV)
+```python
+import MDSplus
+conn = MDSplus.Connection('tcvdata.epfl.ch')
+conn.openTree('tcv_shot', 84000)
+data = conn.get('tcv_eq("I_P")').data()
+```
+
+### PPF (JET)
+```python
+import ppf
+ppf.ppfgo(pulse=99000)
+data, x, t, ier = ppf.ppfget(pulse=99000, dda='EFIT', dtype='Q95')
+```
+
+## Safety
+
+- Always use read-only access modes
+- Never modify data on remote facilities
+- Respect rate limits on data servers

imas_codex-5.0.0rc1/.claude/agents/graph-querier.md

@@ -0,0 +1,58 @@
+---
+name: graph-querier
+description: Query and persist data to the Neo4j knowledge graph. Use for any operation requiring Cypher queries, semantic search, or node creation.
+tools: Bash, Read, Grep
+model: opus
+permissionMode: acceptEdits
+maxTurns: 30
+memory: project
+mcpServers:
+  - codex
+  - imas-ddv4
+skills:
+  - graph-queries
+  - schema-summary
+---
+
+You are a knowledge graph specialist for the imas-codex fusion data graph.
+
+## Capabilities
+
+- Execute Cypher queries via the codex MCP server (`query()`, `add_to_graph()`)
+- Perform semantic search across vector indexes (`semantic_search()`)
+- Create and update graph nodes (IMASMapping, MappingEvidence)
+- Look up IMAS Data Dictionary paths via the imas-ddv4 MCP server
+
+## Rules
+
+1. Always project specific properties in Cypher (`RETURN n.id, n.name`), never full nodes
+2. Use `UNWIND` for batch operations (never loop individual writes)
+3. Track your findings in your agent memory
+4. Never use `DETACH DELETE` without explicit confirmation
+5. For re-embedding: update nodes in place, don't delete and recreate
+
+## Common Queries
+
+```cypher
+-- Count nodes by label
+MATCH (n) RETURN labels(n)[0] AS label, count(n) AS count ORDER BY count DESC
+
+-- Find signals for a physics domain
+MATCH (s:FacilitySignal {facility_id: $facility, physics_domain: $domain})
+RETURN s.id, s.name, s.accessor LIMIT 20
+
+-- Semantic search on descriptions
+CALL db.index.vector.queryNodes($index, $k, $embedding)
+YIELD node, score
+RETURN node.id, node.description, score
+```
+
+## Schema Reference
+
+See [agents/schema-reference.md](../../agents/schema-reference.md) for auto-generated node labels, properties, vector indexes, and relationships.
+
+## Cost Awareness
+
+- Prefer Cypher aggregations over Python post-processing
+- Use `LIMIT` on exploratory queries
+- Cache repeated lookups in variables

imas_codex-5.0.0rc1/.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "env": {
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(ssh *)",
+      "Bash(uv run *)",
+      "Bash(rg *)",
+      "Bash(fd *)",
+      "Bash(eza *)",
+      "Bash(tokei *)",
+      "Bash(git *)",
+      "Bash(curl *)",
+      "Bash(litellm *)",
+      "mcp__codex__*",
+      "mcp__imas-ddv4__*",
+      "Read(.claude/**)"
+    ]
+  }
+}

imas_codex-5.0.0rc1/.claude/skills/facility-access.md

@@ -0,0 +1,86 @@
+# Facility Access Patterns
+
+SSH access and data system patterns per facility.
+
+## SSH Hosts
+
+| Facility | SSH Alias | Data System | Reference Shot |
+|----------|-----------|-------------|----------------|
+| TCV | `tcv` | MDSplus + TDI | 84000 |
+| JET | `jet` | MDSplus + PPF | 99000 |
+| JT-60SA | `jt-60sa` | MDSplus | 30000 |
+| ITER | `iter` | IMAS | N/A |
+
+## Remote Tools
+
+Always prefer these over standard Unix commands:
+- `rg` over `grep -r` (pattern search)
+- `fd` over `find` (file finder — **requires path argument on large FS**)
+- `eza` over `ls -la` / `tree` (directory listing)
+- `tokei` over `wc -l` (LOC by language)
+
+Install on facility: `imas-codex tools install <facility>`
+
+## TCV
+
+### MDSplus Direct
+```python
+import MDSplus
+tree = MDSplus.Tree('tcv_shot', 84000, 'readonly')
+ip = tree.getNode('\\RESULTS::LIUQE:I_P').data()
+```
+
+### TDI Functions
+```python
+import MDSplus
+conn = MDSplus.Connection('tcvdata.epfl.ch')
+conn.openTree('tcv_shot', 84000)
+ip = conn.get('tcv_eq("I_P")').data()
+time = conn.get('dim_of(tcv_eq("I_P"))').data()
+```
+
+### Key Trees
+- `tcv_shot`: Raw diagnostic data
+- `results`: Analysis code outputs (LIUQE, ASTRA, etc.)
+- `atlas`: Magnetics and basic plasma params
+
+### TDI Function Directory
+`/usr/local/mdsplus/tdi/tcv/` — contains `.FUN` files
+
+## JET
+
+### PPF Access
+```python
+import ppf
+ppf.ppfgo(pulse=99000)
+data, x, t, ier = ppf.ppfget(pulse=99000, dda='EFIT', dtype='Q95')
+```
+
+### MDSplus
+```python
+import MDSplus
+conn = MDSplus.Connection('mdsjet.jet.uk')
+conn.openTree('jet', 99000)
+```
+
+### Key DDAs
+- `EFIT`: Equilibrium reconstruction
+- `KK3`: ECE diagnostic
+- `HRTS`: High-res Thomson scattering
+- `BOLO`: Bolometry
+
+## JT-60SA
+
+### MDSplus
+```python
+import MDSplus
+tree = MDSplus.Tree('jt-60sa', 30000, 'readonly')
+```
+
+## Safety Rules
+
+1. **Read-only**: Never modify remote data
+2. **Check excludes first**: `get_facility('tcv')['excludes']`
+3. **Timeout awareness**: Commands on `/work` or `/home` can hang on NFS
+4. **fd needs path**: `fd -e py /specific/path` — never bare `fd` on large FS
+5. **Persist timeouts**: If a path times out, immediately call `update_infrastructure()`

imas_codex-5.0.0rc1/.claude/skills/graph-queries.md

@@ -0,0 +1,60 @@
+# Graph Query Patterns
+
+Common Cypher patterns for the imas-codex Neo4j knowledge graph.
+
+## Node Counts
+```cypher
+MATCH (n) RETURN labels(n)[0] AS label, count(n) AS count ORDER BY count DESC
+```
+
+## Facility Signals by Domain
+```cypher
+MATCH (s:FacilitySignal {facility_id: $facility})
+WHERE s.physics_domain = $domain AND s.status = 'checked'
+OPTIONAL MATCH (s)-[:DATA_ACCESS]->(da:DataAccess)
+RETURN s.id, s.name, s.accessor, da.data_template
+ORDER BY s.name
+```
+
+## Semantic Search + Link Traversal
+```cypher
+CALL db.index.vector.queryNodes($index, $k, $embedding)
+YIELD node AS signal, score
+MATCH (signal)-[:DATA_ACCESS]->(da:DataAccess)
+OPTIONAL MATCH (signal)-[:HAS_DATA_SOURCE_NODE]->(dn:SignalNode)
+    <-[:SOURCE_PATH]-(m:IMASMapping)-[:TARGET_PATH]->(imas:IMASNode)
+RETURN signal.id, signal.description, da.data_template,
+       collect(imas.id) AS imas_paths, score
+ORDER BY score DESC
+```
+
+## IMAS Mappings
+```cypher
+-- Create mapping (status lifecycle: proposed → endorsed → validated | rejected)
+MERGE (m:IMASMapping {id: $id})
+SET m += $props, m.status = 'proposed', m.proposed_at = datetime()
+WITH m
+MATCH (s:FacilitySignal {id: $signal_id})
+MATCH (t:IMASNode {id: $imas_path_id})
+MERGE (m)-[:MAPS_TO_SOURCE]->(s)
+MERGE (m)-[:MAPS_TO_TARGET]->(t)
+
+-- Find mappings needing validation
+MATCH (m:IMASMapping {status: 'proposed', facility_id: $facility})
+RETURN m.id, m.confidence, m.proposed_at
+ORDER BY m.confidence DESC
+```
+
+## Batch Writes (UNWIND)
+```cypher
+UNWIND $items AS item
+MERGE (n:Tool {id: item.id})
+SET n += item
+WITH n
+MATCH (f:Facility {id: $facility})
+MERGE (n)-[:AT_FACILITY]->(f)
+```
+
+## Vector Indexes
+
+See [agents/schema-reference.md](../../agents/schema-reference.md) for the full list of vector indexes derived from the LinkML schema.

imas_codex-5.0.0rc1/.claude/skills/mapping-workflow.md

@@ -0,0 +1,67 @@
+# IMAS Mapping Workflow
+
+How mappings connect facility signals to IMAS fields.
+
+## Architecture
+
+Three symmetric levels:
+
+| Level | Source Side | Target Side |
+|-------|-----------|-------------|
+| Individual | `SignalNode` | `IMASNode` leaf (e.g., FLT_0D) |
+| Group | `SignalSource` | `IMASNode` STRUCT_ARRAY |
+| Collection | `IMASMapping` | `IDS` |
+
+## Graph Structure
+
+```
+IMASMapping ──[:USES_SIGNAL_SOURCE]──▶ SignalSource ──[:MAPS_TO_IMAS {field props}]──▶ IMASNode
+    │                                     ▲
+    │                                [:MEMBER_OF]
+    │                                     │
+    │                              SignalNode / FacilitySignal
+    │
+    └──[:POPULATES {assembly props}]──▶ IMASNode (STRUCT_ARRAY root)
+```
+
+## Key Relationships
+
+| Relationship | From → To | Purpose |
+|---|---|---|
+| `MAPS_TO_IMAS` | SignalSource/SignalNode → IMASNode | Field-level mapping with transform |
+| `POPULATES` | IMASMapping → IMASNode (STRUCT_ARRAY) | Assembly section target with config |
+| `USES_SIGNAL_SOURCE` | IMASMapping → SignalSource | Assembly sources |
+| `MEMBER_OF` | SignalNode/FacilitySignal → SignalSource | Group membership |
+| `HAS_EVIDENCE` | SignalSource → MappingEvidence | Evidence for group's mapping |
+
+## MAPS_TO_IMAS Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `source_property` | string | Field on SignalNode to extract (e.g., "r", "z") |
+| `transform_code` | string | Python expression with `value` as input |
+| `units_in` | string | Source units |
+| `units_out` | string | Target units |
+| `status` | string | "validated" or "proposed" |
+| `confidence` | float | 0.0-1.0 |
+| `cocos_source` | integer | Source COCOS convention |
+| `cocos_target` | integer | Target COCOS convention |
+
+## Full Traversal Query
+
+```cypher
+MATCH (m:IMASMapping {id: $mapping_id})
+      -[t:POPULATES]->(root:IMASNode)
+MATCH (root)<-[:HAS_PARENT*]-(leaf:IMASNode)
+      <-[map:MAPS_TO_IMAS]-(sg:SignalSource)
+      <-[:MEMBER_OF]-(n:SignalNode)
+WHERE (m)-[:USES_SIGNAL_SOURCE]->(sg)
+RETURN leaf.id, map.source_property, map.transform_code, n.path
+```
+
+## Key Checks
+
+- **Units**: Must be pint-compatible. Use `pint.UnitRegistry()` to verify conversion.
+- **Sign convention**: Check COCOS. TCV uses COCOS 17 for equilibrium.
+- **Array shape**: IMAS expects specific dimension ordering (time last in many cases).
+- **NaN handling**: Check for NaN/inf in source data before mapping.

imas_codex-5.0.0rc1/.claude/skills/schema-summary.md

@@ -0,0 +1,123 @@
+# Graph Schema Summary
+
+Condensed schema for the imas-codex Neo4j knowledge graph.
+
+**Before writing Cypher queries**, verify property names against this reference.
+For the full schema (53 node types), see `agents/schema-reference.md` or call `get_graph_schema()`.
+
+## Core Node Types
+
+| Type | Key Fields | Description |
+|------|-----------|-------------|
+| Facility | id, name, machine | Root node per facility (tcv, jet, iter, jt-60sa) |
+| FacilitySignal | id, physics_domain, accessor, status | Signal with access info |
+| DataAccess | id, method_type, data_template, time_template | Code generation template |
+| SignalNode | path, tree_name, node_type, description | MDSplus tree node |
+| TDIFunction | id, name, supported_quantities | TDI accessor function |
+| IMASNode | id (DD path), description, units | IMAS Data Dictionary path |
+| IMASMapping | id, facility_id, physics_domain, status | IDS mapping orchestration node |
+| MappingEvidence | id, evidence_type, content | Evidence supporting a mapping |
+| WikiPage | id, url, title, status, score | Wiki documentation page |
+| WikiChunk | id, **text**, embedding | Searchable wiki text chunk |
+| CodeChunk | id, **text**, embedding | Searchable code chunk |
+| Image | id, source_url, description, embedding | Visual resource from wiki/docs |
+
+## WikiChunk Properties (complete)
+
+| Property | Type | Notes |
+|----------|------|-------|
+| id | string | e.g. "tcv:Thomson:chunk_0" |
+| wiki_page_id | string | Parent WikiPage ID |
+| artifact_id | string | Parent WikiArtifact ID (for doc chunks) |
+| facility_id | string | Facility filter |
+| chunk_index | integer | Position in document (0-based) |
+| section | string | Section heading |
+| **text** | string | **The actual text content** |
+| embedding | float[] | Vector for semantic search |
+| mdsplus_paths_mentioned | string[] | e.g. ["\\ATLAS::IP"] |
+| imas_paths_mentioned | string[] | e.g. ["equilibrium/time_slice/profiles_1d/psi"] |
+| ppf_paths_mentioned | string[] | JET PPF paths |
+| units_mentioned | string[] | e.g. ["eV", "Tesla"] |
+| conventions_mentioned | string[] | e.g. ["COCOS 11"] |
+| tool_mentions | string[] | e.g. ["tdiExecute", "ppfget"] |
+
+## Canonical Query Patterns
+
+### Wiki semantic search
+```cypher
+CALL db.index.vector.queryNodes('wiki_chunk_embedding', $k, $embedding)
+YIELD node, score
+MATCH (p:WikiPage)-[:HAS_CHUNK]->(node)
+WHERE p.facility_id = $facility
+RETURN p.title AS page_title, p.url AS url, node.text AS text, score
+ORDER BY score DESC
+```
+
+### Wiki chunks for a path
+```cypher
+MATCH (wc:WikiChunk)-[:DOCUMENTS]->(t:SignalNode)
+WHERE t.path CONTAINS $path
+MATCH (wp:WikiPage)-[:HAS_CHUNK]->(wc)
+RETURN wp.title AS page_title, wc.text AS text
+LIMIT 5
+```
+
+### Signal semantic search
+```cypher
+CALL db.index.vector.queryNodes('facility_signal_desc_embedding', $k, $embedding)
+YIELD node AS signal, score
+MATCH (signal)-[:DATA_ACCESS]->(da:DataAccess)
+OPTIONAL MATCH (signal)-[:HAS_DATA_SOURCE_NODE]->(dn:SignalNode)
+RETURN signal.id, signal.description, da.data_template, score
+ORDER BY score DESC
+```
+
+### Image search
+```cypher
+CALL db.index.vector.queryNodes('image_desc_embedding', $k, $embedding)
+YIELD node, score
+RETURN node.description, node.source_url, node.keywords, score
+ORDER BY score DESC
+```
+
+## Vector Indexes
+
+| Index | Node | Search By |
+|-------|------|-----------|
+| wiki_chunk_embedding | WikiChunk | Wiki text content |
+| code_chunk_embedding | CodeChunk | Code content |
+| image_desc_embedding | Image | Image description/caption |
+| facility_signal_desc_embedding | FacilitySignal | Signal description |
+| facility_path_desc_embedding | FacilityPath | Path description |
+| imas_node_embedding | IMASNode | DD path description |
+| signal_node_desc_embedding | SignalNode | Data node description |
+| wiki_artifact_desc_embedding | WikiArtifact | Artifact description |
+| cluster_embedding | IMASSemanticCluster | Cluster content |
+
+## Key Relationships
+
+| From | Relationship | To |
+|------|-------------|-----|
+| FacilitySignal | DATA_ACCESS | DataAccess |
+| FacilitySignal | HAS_DATA_SOURCE_NODE | SignalNode |
+| FacilitySignal | AT_FACILITY | Facility |
+| SignalNode | AT_FACILITY | Facility |
+| IMASMapping | AT_FACILITY | Facility |
+| WikiChunk | HAS_CHUNK ← | WikiPage |
+| WikiChunk | NEXT_CHUNK | WikiChunk |
+| CodeChunk | HAS_CHUNK ← | CodeExample |
+
+## Status Enums
+
+| Type | States |
+|------|--------|
+| FacilitySignal | discovered → enriched → checked / skipped / failed |
+| WikiPage | scanned → scored → ingested / skipped / failed |
+| IMASMapping | proposed → endorsed / contested → validated / rejected |
+
+## Physics Domains (PhysicsDomain enum)
+
+equilibrium, magnetics, electron_density, electron_temperature,
+ion_temperature, radiation, neutron, spectroscopy, mhd,
+heating_current_drive, fueling, vacuum, wall, divertor,
+current_drive, transport, turbulence, pedestal, core_profiles

imas_codex-5.0.0rc1/.cursor/mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "codex": {
+      "command": "uv",
+      "args": ["run", "imas-codex", "serve", "agents"]
+    },
+    "imas": {
+      "url": "https://imas-dd.iter.org/mcp",
+      "type": "http"
+    }
+  }
+}

imas_codex-5.0.0rc1/.dockerignore

@@ -0,0 +1,57 @@
+# Multi-stage build optimization
+# Keep .git for dynamic versioning but minimize other cache-busting files
+
+# Python cache files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+tests/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS specific
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Logs
+*.log
+
+# Documentation, plans, and tooling (not needed at runtime)
+docs/
+plans/
+agents/
+benchmarks/
+slurm/
+
+# File-based data artifacts (graph-native mode uses Neo4j)
+*.pkl
+*.npz
+*.dump
+
+# Git files - keep essential ones for dynamic versioning
+# .git/objects/  # Keep objects for setuptools-scm
+# .git/refs/     # Keep refs for setuptools-scm
+.git/refs/remotes/
+.git/logs/
+.git/hooks/

imas_codex-5.0.0rc1/.github/agents/develop.agent.md

@@ -0,0 +1,41 @@
+---
+name: Develop
+description: Code development with testing and git workflow guardrails
+tools:
+  - standard
+  - codex/*
+handoffs:
+  - label: Update Graph Schema
+    agent: graph
+    prompt: Update the knowledge graph schema based on the code changes.
+    send: false
+---
+
+# Develop Agent
+
+You are a **development agent** with full editing capabilities but structured workflow guardrails. You have access to file editing, terminal commands, and testing tools.
+
+## Your Role
+
+- Implement features and fix bugs
+- Run tests before committing
+- Follow conventional commit format
+- Use `ruff` for linting before commits
+
+## Workflow
+
+1. Make code changes with `editFiles`
+2. Run `uv run ruff check --fix . && uv run ruff format .`
+3. Run `uv run pytest` to verify
+4. Stage specific files (never `git add -A`)
+5. Commit with `uv run git commit -m 'type: description'`
+
+## Restrictions
+
+- Always run tests before committing
+- Use single quotes for commit messages
+- Stage files individually, not with `-A`
+
+## Full Instructions
+
+See [agents/develop.md](../../agents/develop.md) for complete development workflows, testing patterns, and commit conventions.

imas_codex-5.0.0rc1/.github/agents/explore.agent.md

@@ -0,0 +1,48 @@
+---
+name: Explore
+description: Remote facility exploration - SSH, file discovery, pattern search. Read-only access.
+tools:
+  - codebase
+  - readFile
+  - listDirectory
+  - fileSearch
+  - textSearch
+  - fetch
+  - problems
+  - usages
+  - terminalLastCommand
+  - codex/*
+handoffs:
+  - label: Queue for Ingestion
+    agent: Ingest
+    prompt: Queue the discovered source files for code ingestion.
+    send: false
+  - label: Persist to Graph
+    agent: Graph
+    prompt: Persist the exploration findings to the knowledge graph.
+    send: false
+---
+
+# Explore Agent
+
+You are a **read-only exploration agent** for remote fusion facility discovery. You have access to the `codex` MCP server tools (`python`, `get_graph_schema`, `ingest_nodes`, `private`) but **no file editing capabilities**.
+
+## Your Role
+
+- **Check locality first** (`hostname`) before choosing execution method
+- **Local facility**: Use terminal directly for single commands (`rg`, `fd`, `tokei`)
+- **Remote facility**: Use direct SSH for single commands (`ssh facility "command"`)
+- Use `python()` only for chained processing and graph operations
+- Discover source files, MDSplus trees, analysis codes
+- Track exploration progress with `FacilityPath` nodes
+- Persist discoveries using `ingest_nodes()` and `private()`
+
+## Restrictions
+
+- **No file editing** - use handoffs to `develop` agent for code changes
+- **No git operations** - exploration only
+- **Read-only workspace access** - can search and read, not modify
+
+## Full Instructions
+
+See [agents/explore.md](../../agents/explore.md) for complete exploration workflows, SSH patterns, remote tool usage, and persistence checklists.