chore: Refined link map

agents/projects/links/AGENT_TOOLS_README.md

@@ -0,0 +1,290 @@
+# Agent Tools for Keyword Linking Analysis
+
+This directory contains tools to analyze and advance the keyword linking system using the AI-generated `agent_reference_revised_manual.json`.
+
+## Available Tools
+
+### 1. `analyze_links.py` - Overall Coverage Analysis
+
+Shows the big picture of link type implementation status.
+
+```bash
+python analyze_links.py
+```
+
+**Output:**
+- Currently implemented link types (20)
+- Missing link types (98) sorted by priority
+- Conditional link summary
+- Recommendations for next steps
+
+**Use this when:**
+- You want to understand current coverage
+- You're planning which link types to implement next
+- You need metrics for documentation
+
+---
+
+### 2. `extract_link_info.py` - Detailed Link Type Analysis
+
+Analyzes specific link types and generates code snippets for implementation.
+
+```bash
+python extract_link_info.py <link_type_id> [link_type_id...]
+```
+
+**Example:**
+```bash
+python extract_link_info.py 92 84 120
+```
+
+**Output for each link type:**
+- Total references and confidence score
+- Source keywords using this link
+- Sample field names
+- Target keyword types
+- Ready-to-use code snippets for:
+  - LinkType enum entry
+  - LinkIdentity constant
+  - Handler function
+  - Integration points in codegen
+
+**Use this when:**
+- Implementing a new link type
+- Understanding what keywords use a specific link
+- Generating boilerplate code
+
+---
+
+### 3. `analyze_conditional_links.py` - Conditional Link Patterns
+
+Analyzes the complex conditional links (type -1) where target depends on another field.
+
+```bash
+python analyze_conditional_links.py
+```
+
+**Output:**
+- Control field analysis (e.g., SIDTYP)
+- Value map patterns
+- Implementation recommendations
+- Standard SIDTYP value map reference
+
+**Use this when:**
+- Designing the conditional link feature
+- Understanding AIRBAG/CONTACT keyword polymorphism
+- Planning the ConditionalLink implementation
+
+---
+
+## Data Source: `agent_reference_revised_manual.json`
+
+This 110,000+ line JSON file was generated by AI analysis of the LS-DYNA keyword manual and contains:
+
+### Structure
+
+```json
+{
+  "19": [                          // Simple link (DEFINE_CURVE)
+    {
+      "source_keyword": "MAT_...",
+      "source_field": "lcid",
+      "referenced_keywords": ["DEFINE_CURVE"],
+      "confidence": 0.95
+    }
+  ],
+  "-1": [                          // Conditional link
+    {
+      "source_keyword": "CONTACT_...",
+      "source_field": "ssid",
+      "referenced_keywords": ["SET_SEGMENT", "SET_PART"],
+      "condition": {
+        "field": "sstyp",
+        "value_map": {
+          "0": "SET_SEGMENT",
+          "2": "SET_PART"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Key Metrics
+
+- **118 link types** identified
+- **~6,500 total field references** across all keywords
+- **842 conditional links** (all using SIDTYP pattern)
+- **Confidence scores** range from 0.60 to 0.95
+
+### Coverage by Domain
+
+| Domain | Implemented | Available | Coverage |
+|--------|-------------|-----------|----------|
+| DEFINE_* | 8 | 20 | 40% |
+| SET_* | 7 | 15 | 47% |
+| ELEMENT_* | 3 | 7 | 43% |
+| IGA_* | 0 | 8 | 0% |
+| All | 20 | 118 | 17% |
+
+---
+
+## Implementation Workflow
+
+### Adding a New Simple Link Type
+
+1. **Analyze the link type:**
+   ```bash
+   python extract_link_info.py 92
+   ```
+
+2. **Add to `keyword_base.py`:**
+   ```python
+   class LinkType(enum.Enum):
+       # ... existing ...
+       DEFINE_FUNCTION = 92
+       """Reference to a DEFINE_FUNCTION keyword."""
+   ```
+
+3. **Add to `class_generator.py` LinkIdentity:**
+   ```python
+   class LinkIdentity:
+       # ... existing ...
+       DEFINE_FUNCTION = 92
+   ```
+
+4. **Add handler function in `class_generator.py`:**
+   ```python
+   def _add_define_function_link_data(link_data, link_fields):
+       """Add link data for DEFINE_FUNCTION keywords."""
+       link_data_dict = {
+           "classname": "DefineFunction",
+           "modulename": "define.define_function",
+           "keyword_type": "DEFINE",
+           "keyword_subtype": "FUNCTION",
+           "fields": _convert_link_fields_to_template_format(link_fields),
+           "linkid": "fid",
+           "link_type_name": "DEFINE_FUNCTION",
+       }
+       link_data.append(link_data_dict)
+   ```
+
+5. **Add to `_get_links()` dict:**
+   ```python
+   links = {
+       # ... existing ...
+       LinkIdentity.DEFINE_FUNCTION: [],
+   }
+   ```
+
+6. **Add to `_add_links()` elif chain:**
+   ```python
+   elif link_type == LinkIdentity.DEFINE_FUNCTION:
+       _add_define_function_link_data(link_data, link_fields)
+       link_count += len(link_fields)
+   ```
+
+7. **Regenerate code and test:**
+   ```bash
+   python codegen/generate.py
+   pytest tests/test_keyword_links.py -v
+   ```
+
+---
+
+## Priority Queue (Based on Analysis)
+
+### Immediate (High-Value, High-Confidence)
+
+1. **Link 92: DEFINE_FUNCTION** (131 refs, 0.95 conf)
+2. **Link 84: DEFINE_CPM_CHAMBER** (128 refs, 0.95 conf)
+3. **Link 120: DEFINE_CPM_VENT** (128 refs, 0.95 conf)
+
+### Short Term (Complete SET_* Family)
+
+4. **Link 30: SET_SHELL** (44 refs, 0.95 conf)
+5. **Link 32: SET_TSHELL** (21 refs, 0.95 conf)
+6. **Link 33: CONTACT** (40 refs, 0.95 conf)
+
+### Medium Term (IGA Support)
+
+7. **Link 124: IGA_EDGE_XYZ** (79 refs, 0.95 conf)
+8. **Link 127: IGA_FACE_XYZ** (64 refs, 0.95 conf)
+9. **Link 134: IGA_POINT_UVW** (55 refs, 0.95 conf)
+10. **Link 131: IGA_FACE_UVW** (53 refs, 0.95 conf)
+
+### Long Term (Advanced Features)
+
+11. **Conditional Links (-1)** (842 entries)
+    - Requires framework design
+    - SIDTYP pattern is consistent
+    - Mainly AIRBAG and CONTACT keywords
+
+---
+
+## Testing New Link Types
+
+After adding a link type, verify it works:
+
+```python
+# tests/test_keyword_links.py
+
+def test_define_function_link():
+    """Test DEFINE_FUNCTION link type."""
+    deck = Deck()
+
+    func = kwd.DefineFunction()
+    func.fid = 100
+
+    mat = kwd.Mat106()  # Uses DEFINE_FUNCTION
+    mat.dfid = 100
+
+    deck.extend([func, mat])
+
+    # Property access
+    assert mat.dfid_link is func
+
+    # get_links method
+    links = mat.get_links(LinkType.DEFINE_FUNCTION)
+    assert len(links) == 1
+    assert links[0] is func
+```
+
+---
+
+## Conditional Links (Future Work)
+
+The conditional link feature will require:
+
+1. **Metadata structure:**
+   ```python
+   @dataclass
+   class ConditionalLink:
+       control_field: str
+       value_map: Dict[str, LinkType]
+       default: Optional[LinkType] = None
+   ```
+
+2. **Template updates:**
+   - Generate conditional logic in `*_link` properties
+   - Check control field value at runtime
+
+3. **Codegen integration:**
+   - Parse `-1` entries from JSON
+   - Generate ConditionalLink metadata
+   - Add to _link_fields dict
+
+4. **Test coverage:**
+   - Test all SIDTYP values
+   - Test default behavior
+   - Test with missing control field
+
+---
+
+## Questions?
+
+See:
+- `LINK_ADVANCEMENT_SUMMARY.md` - Detailed analysis and roadmap
+- `agents/keywords/linking.md` - Linking pattern documentation
+- `test_keyword_links.py` - Current test coverage
+- DeepWiki: https://deepwiki.com/ansys/pydyna (keyword linking section)