استفاده از مدل‌های زبانی (LLM) برای نمونه‌سازی اسکریپت‌های برنامه‌ریزی در Cisco Crosswork

Source plan: sr_topo_base.txt (44677 bytes)
Mapping CSV: /opt/execute/job/47/circuitid_mappings.csv
Loaded 15 usable mapping row(s).
Matched CSV line 2 to circuit 10.4.8.0/28.
Matched CSV line 3 to circuit 2001::1:6:1/112.
Matched CSV line 4 to circuit 10.5.6.4/30.
Matched CSV line 5 to circuit 10.5.8.0/28.
Matched CSV line 6 to circuit 2001::4:5:4/112.
Matched CSV line 7 to circuit 10.1.5.0/29.
Matched CSV line 8 to circuit 10.2.6.0/29.
Matched CSV line 9 to circuit 10.1.2.0/30.
Matched CSV line 10 to circuit 10.3.8.0/28.
Matched CSV line 11 to circuit 2001::3:4:3/112.
Matched CSV line 12 to circuit 2001::3:7:3/112.
Matched CSV line 13 to circuit 10.7.8.0/28.
Matched CSV line 14 to circuit 2001::2:7:2/112.
Matched CSV line 15 to circuit 10.6.7.6/31.
Matched CSV line 16 to circuit 2001::5:7:5/112.
Changed: node-4/GigabitEthernet0/0/0/8: 'Connection to device node-8 destination interface 4' -> 'Connection to device node-8 destination interface 4 (Circuit ID: SR/IPIG/483921/CNC)'
Changed: node-8/GigabitEthernet0/0/0/4: 'Connection to device node-4 destination interface 8' -> 'Connection to device node-4 destination interface 8 (Circuit ID: SR/IPIG/483921/CNC)'
Changed: node-1/GigabitEthernet0/0/0/6: 'Connection to device node-6 destination interface 1' -> 'Connection to device node-6 destination interface 1 (Circuit ID: SR/IPIG/716304/CNC)'
Changed: node-6/GigabitEthernet0/0/0/1: 'Connection to device node-1 destination interface 6' -> 'Connection to device node-1 destination interface 6 (Circuit ID: SR/IPIG/716304/CNC)'
Changed: node-5/GigabitEthernet0/0/0/6: 'Connection to device node-6 destination interface 5' -> 'Connection to device node-6 destination interface 5 (Circuit ID: SR/IPIG/259847/CNC)'
Changed: node-6/GigabitEthernet0/0/0/5: 'Connection to device node-5 destination interface 6' -> 'Connection to device node-5 destination interface 6 (Circuit ID: SR/IPIG/259847/CNC)'
Changed: node-5/GigabitEthernet0/0/0/8: 'Connection to device node-8 destination interface 5' -> 'Connection to device node-8 destination interface 5 (Circuit ID: SR/IPIG/904162/CNC)'
Changed: node-8/GigabitEthernet0/0/0/5: 'Connection to device node-5 destination interface 8' -> 'Connection to device node-5 destination interface 8 (Circuit ID: SR/IPIG/904162/CNC)'
Changed: node-4/GigabitEthernet0/0/0/5: 'Connection to device node-5 destination interface 4' -> 'Connection to device node-5 destination interface 4 (Circuit ID: SR/IPIG/638075/CNC)'
Changed: node-5/GigabitEthernet0/0/0/4: 'Connection to device node-4 destination interface 5' -> 'Connection to device node-4 destination interface 5 (Circuit ID: SR/IPIG/638075/CNC)'
Changed: node-1/GigabitEthernet0/0/0/5: 'Connection to device node-5 destination interface 1' -> 'Connection to device node-5 destination interface 1 (Circuit ID: SR/IPIG/147593/CNC)'
Changed: node-5/GigabitEthernet0/0/0/1: 'Connection to device node-1 destination interface 5' -> 'Connection to device node-1 destination interface 5 (Circuit ID: SR/IPIG/147593/CNC)'
Changed: node-2/GigabitEthernet0/0/0/6: 'Connection to device node-6 destination interface 2' -> 'Connection to device node-6 destination interface 2 (Circuit ID: SR/IPIG/825416/CNC)'
Changed: node-6/GigabitEthernet0/0/0/2: 'Connection to device node-2 destination interface 6' -> 'Connection to device node-2 destination interface 6 (Circuit ID: SR/IPIG/825416/CNC)'
Changed: node-1/GigabitEthernet0/0/0/2: 'Connection to device node-2 destination interface 1' -> 'Connection to device node-2 destination interface 1 (Circuit ID: SR/IPIG/371968/CNC)'
Changed: node-2/GigabitEthernet0/0/0/1: 'Connection to device node-1 destination interface 2' -> 'Connection to device node-1 destination interface 2 (Circuit ID: SR/IPIG/371968/CNC)'
Changed: node-3/GigabitEthernet0/0/0/8: 'Connection to device node-8 destination interface 3' -> 'Connection to device node-8 destination interface 3 (Circuit ID: SR/IPIG/592731/CNC)'
Changed: node-8/GigabitEthernet0/0/0/3: 'Connection to device node-3 destination interface 8' -> 'Connection to device node-3 destination interface 8 (Circuit ID: SR/IPIG/592731/CNC)'
Changed: node-3/GigabitEthernet0/0/0/4: 'Connection to device node-4 destination interface 3' -> 'Connection to device node-4 destination interface 3 (Circuit ID: SR/IPIG/068459/CNC)'
Changed: node-4/GigabitEthernet0/0/0/3: 'Connection to device node-3 destination interface 4' -> 'Connection to device node-3 destination interface 4 (Circuit ID: SR/IPIG/068459/CNC)'
Changed: node-3/GigabitEthernet0/0/0/7: 'Connection to device node-7 destination interface 3' -> 'Connection to device node-7 destination interface 3 (Circuit ID: SR/IPIG/943287/CNC)'
Changed: node-7/GigabitEthernet0/0/0/3: 'Connection to device node-3 destination interface 7' -> 'Connection to device node-3 destination interface 7 (Circuit ID: SR/IPIG/943287/CNC)'
Changed: node-7/GigabitEthernet0/0/0/8: 'Connection to device node-8 destination interface 7' -> 'Connection to device node-8 destination interface 7 (Circuit ID: SR/IPIG/410826/CNC)'
Changed: node-8/GigabitEthernet0/0/0/7: 'Connection to device node-7 destination interface 8' -> 'Connection to device node-7 destination interface 8 (Circuit ID: SR/IPIG/410826/CNC)'
Changed: node-2/GigabitEthernet0/0/0/7: 'Connection to device node-7 destination interface 2' -> 'Connection to device node-7 destination interface 2 (Circuit ID: SR/IPIG/786152/CNC)'
Changed: node-7/GigabitEthernet0/0/0/2: 'Connection to device node-2 destination interface 7' -> 'Connection to device node-2 destination interface 7 (Circuit ID: SR/IPIG/786152/CNC)'
Changed: node-6/GigabitEthernet0/0/0/7: 'Connection to device node-7 destination interface 6' -> 'Connection to device node-7 destination interface 6 (Circuit ID: SR/IPIG/235694/CNC)'
Changed: node-7/GigabitEthernet0/0/0/6: 'Connection to device node-6 destination interface 7' -> 'Connection to device node-6 destination interface 7 (Circuit ID: SR/IPIG/235694/CNC)'
Changed: node-5/GigabitEthernet0/0/0/7: 'Connection to device node-7 destination interface 5' -> 'Connection to device node-7 destination interface 5 (Circuit ID: SR/IPIG/651379/CNC)'
Changed: node-7/GigabitEthernet0/0/0/5: 'Connection to device node-5 destination interface 7' -> 'Connection to device node-5 destination interface 7 (Circuit ID: SR/IPIG/651379/CNC)'
Loaded mapping rows: 15
Mapped plan endpoints: 30
Changed descriptions: 30
Output plan written: sr_topo_base_out.txt

# Crosswork Planning APIs and Libraries
## Overview for new users
Cisco Crosswork Planning represents an IP/MPLS network as a model that can be examined and changed offline. The model brings together topology, traffic, routing configuration, and object state. Operators can use it to ask questions such as: *What happens if a link fails? How will planned traffic growth affect utilization? Which metric or tunnel changes could reduce congestion?*
The Design application provides the graphical workflow. Scripts and other applications can use the **Design RPC Python Library** and the **Optimization and Prediction Module (OPM) Python Library** to work with the same server-side design engine. The Design RPC library exposes the underlying objects and operations; OPM wraps it with a higher-level Python interface. The engine manages model objects and performs simulation and optimization. Cisco describes most model-building and simulation capabilities as available through the API, while the published REST API is initially the OPM Service API. [Crosswork Planning API overview](https://developer.cisco.com/docs/crosswork/planning/)
A typical automation flow is:
1. **Load a model.** Open a local plan file through the library, or retrieve a collector model from the Modeling Daemon (WMD).
2. **Inspect or change the model.** Read objects, adjust traffic or topology, and set object state.
3. **Run an analysis or optimization.** Submit the modeled scenario to the design engine.
4. **Review and use the result.** Examine the resulting model and reports, then save or pass the output into a subsequent workflow.
A plan file represents one network and can contain configurations, routes, measured traffic, an estimated traffic matrix, object states, and analysis results. Crosswork Planning documents `.pln` files for compact use in the application and tab-delimited `.txt` files for direct editing. [Core concepts](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/get-started/core-concepts.html)
## Loading a network model
The SDK runs on a Linux client and connects to the Crosswork Planning VM's `designapi` service. Cisco's 7.2 example reads a local plan file on the client and sends its bytes to the server-side engine. The OPM version presents the loaded network through `plan.model`. [Customization scripts and library setup](https://developer.cisco.com/docs/crosswork/planning/customization-scripts-using-crosswork-planning-designopm-library-package/)
```python
from com.cisco.wae.opm.network import open_plan
with open_plan(plan_file, host, 30744, "ssl") as plan:
 model = plan.model
 for node in model.nodes:
 print(node.name)
```
The SDK guide also shows WMD as an alternative source: WMD maintains a working collector model, and an OPM `WMDClient` can retrieve a copy for a script to inspect or use. [WMD and library examples](https://developer.cisco.com/docs/crosswork/planning/customization-scripts-using-crosswork-planning-designopm-library-package/)
For the documented 7.2 package, Cisco specifies Linux, Python 3.12 or later, TLS certificates, and an authenticated Crosswork account with administrator access. The library package connects to the service over SSL; the guide uses port `30744`. [Library requirements and connection example](https://developer.cisco.com/docs/crosswork/planning/customization-scripts-using-crosswork-planning-designopm-library-package/)
## Model constructs and operations
A **plan object** represents a network element or planning construct. Objects have properties and state that affect the simulated network. The available model is broader than a topology graph: plan files can include traffic, routing, service classes, paths, and analysis results. [Plan files and objects](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/get-started/core-concepts.html)
| Model area | Representative objects and constructs | How they are used |
|---|---|---|
| Topology | Nodes, sites, interfaces, circuits | Represent routers, logical groupings, and links. Interfaces carry routing properties such as metrics; circuits describe connections and capacity. |
| Physical and shared risk | Ports, port circuits, link aggregation groups (LAGs), Shared Risk Link Groups (SRLGs) | Model physical members, bundled links, and elements that could fail together. |
| Traffic | Demands and demand meshes, measured traffic, traffic matrices, growth plans | Represent source-to-destination traffic, estimate demand from measurements, and model future growth. |
| Routing and traffic engineering | Label-switched paths (LSPs), LSP paths, RSVP-TE and Segment Routing (SR) constructs | Represent tunnels, explicit or calculated paths, protection, and routing of demands through LSPs. |
| Services and routing context | VPNs, multicast flows, service classes, routing protocols | Add service and protocol context to the network model and simulation. |
| State and scenarios | Active/inactive and failed states; topology and metric changes | Define the modeled network condition and evaluate what-if scenarios. |
Crosswork Planning's documented plan-object operations include creating, modifying, and deleting objects. The model can also be changed by applying failures or administrative state, changing metrics or topology, and editing demand traffic. [Plan object concepts](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/understand-plan-objects.html) [Object states](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/simulation-overview/states-of-plan-objects.html)
## Simulation and analysis
The simulation engine evaluates traffic against the modeled topology, routing configuration, and object state. The existing **Analyze** capabilities provide useful categories for describing the kinds of work that can be automated:
- **What-if analysis:** model failures, topology changes, metric changes, and demand changes.
- **Failure analysis:** evaluate worst-case interface utilization or demand latency across selected failure scenarios, including pairwise failures.
- **Traffic growth and capacity planning:** project demand growth and evaluate capacity changes against utilization targets.
- **Routing and service simulation:** model IGP or BGP behavior, LSP routing, VPNs, multicast, and quality-of-service (QoS) settings where represented in the plan.
These categories are documented in the Crosswork Planning Design guide. The API overview positions the libraries as a way for scripts and applications to evaluate models on the server engine; the exact operation and object coverage should be checked against the SDK package for the deployed release. [Analyze and simulation topics](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/doc_portal/CrossworkPlanning_info_center.html) [Design RPC and OPM overview](https://developer.cisco.com/docs/crosswork/planning/)
## Optimization and traffic engineering
**Optimize** and **Traffic Engineering** use the modeled traffic and routing state to evaluate changes to network metrics, capacity, or paths.
- **Metric optimization** can target maximum interface utilization, the number of interfaces above a threshold, latency bounds, and selected failure scenarios. It can optimize for normal operation or account for resilient operation across failures. [Metric optimization options](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/optimize-metrics/perform-metric-optimization.html)
- **LSP optimization** includes disjoint-path, load-share, and setup-bandwidth workflows. RSVP-TE and SR-TE options support path and bandwidth planning. [Optimization topics](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/doc_portal/CrossworkPlanning_info_center.html)
- **SR-TE optimization** can optimize path metrics such as IGP metric, TE metric, or delay, and can constrain paths to avoid selected nodes, interfaces, or SRLGs. [SR-TE optimization](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/optimize-segment-routing/sr-te-optimizations.html)
- **Capacity planning** can model circuit upgrades, new adjacencies, parallel circuits, or port circuits (LAGs), with utilization thresholds, capacity increments, failure sets, and capacity or cost objectives. [Capacity planning options](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/perform-capacity-planning/perform-capacity-planning-optimization.html)
- **Traffic engineering** represents LSPs and their paths, and can route demands through those LSPs. The Design guide documents RSVP-TE constructs such as named and actual paths, Fast Reroute, and point-to-multipoint LSPs, alongside SR constructs such as segment types, segment lists, SIDs, and protection. [Traffic Engineering topics](https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/doc_portal/CrossworkPlanning_info_center.html)
This gives a practical way to describe the relationship to current product capabilities: the GUI exposes Analyze, Optimize, and Traffic Engineering workflows; the libraries let automation build or alter a model and invoke engine-backed work programmatically. For a specific deployment, confirm which functions are exposed by its matching SDK release rather than assuming every GUI action has an identical library call.
## Version and scope notes
The OPM library release notes for version 7.2 list Layer 1 (L1) objects—including L1 nodes, links, ports, circuits, paths, and L3-to-L1 links—and user tables. This documents model-object support in that library version; it does not by itself establish which L1 simulation or optimization workflows are available. [OPM library release notes](https://developer.cisco.com/docs/crosswork/planning/crosswork-planning-opm-python-library/)
The public API overview distinguishes the REST OPM Service API from the Design RPC and OPM Python libraries. The REST API uses HTTPS and JSON; the Python package connects to the design service using TLS. Treat the package and service version as a matched set, and use the SDK's included API documentation to confirm object attributes and callable operations for the installed release. [Crosswork Planning API overview](https://developer.cisco.com/docs/crosswork/planning/)

Generate a single, complete Python script named `append_circuit_id.py` for Cisco Crosswork Planning. Return only the contents of the Python file in one code block. Do not return a README, tests, explanation, pseudocode, or additional files.
### Reference material and supported API
Use these Cisco references as the API/runtime authority:
- Crosswork Planning Design RPC / OPM Python library: https://developer.cisco.com/docs/crosswork/planning/libraries-crosswork-planning-design-rpc-python-library/
- Crosswork Planning Design 7.2 guide, "Run external scripts": https://www.cisco.com/c/en/us/td/docs/cloud-systems-management/crosswork-planning/7-2/design-guide/cisco-crosswork-planning-design-user-guide-7-2/view-jobs/run-external-scripts.html
The script runs inside the Crosswork Planning Python environment, where `from com.cisco.wae.opm.network import Network` is available. Follow the documented external-script contract: `sys.argv[1]` is the source plan path, `sys.argv[2]` is the destination plan path, and `Network(source_path)` opens the model and `network.write(destination_path)` writes it. Do not substitute a generic plan-file parser or introduce third-party dependencies. Additional Collector arguments may be present; use `sys.argv[6]` as an optional user-uploaded external-files directory, and ignore other extra arguments.
### Purpose and data format
Read a file named exactly `circuitid_mappings.csv`. It has a header row with these required, case-sensitive columns:
```csv
Circuit ID,NodeA,InterfaceA,NodeB,InterfaceB
```
Each non-empty data row maps one circuit ID to two node/interface endpoints. Read the CSV at runtime using Python's standard `csv` module. Strip leading and trailing whitespace from all field values. Skip and log rows where any required value is empty. A missing file, empty CSV, or missing required header must produce a useful error.
Locate the CSV by checking these directories in order, using the first matching file and avoiding duplicate directories:
1. Directory containing this script.
2. Directory containing the source plan.
3. Current working directory.
4. The optional `sys.argv[6]` directory, if supplied and valid.
If the CSV cannot be found, raise a readable error that names the expected filename and directories searched.
### Matching and updates
Use the OPM network model. Prefer matching `network.model.circuits`: each circuit has `interface_a` and `interface_b`; each interface has `name`, `description`, and a parent `node.name`. Match a CSV circuit using both `(node name, interface name)` endpoint pairs, independent of endpoint order. Strip whitespace before comparing names. For each matched circuit, update the descriptions on both endpoint interfaces.
If a CSV row does not match a circuit object, fall back to resolving its two named interfaces through `network.model.nodes` and each node's `interfaces` collection. Support both keyed collection lookup and iteration by object `.name` so the code works with either mapping-like or iterable OPM collections. Update whichever endpoint interfaces exist; log a missing interface. Log a CSV mapping as unmatched only if neither endpoint interface could be found.
Append this exact suffix to each applicable interface description:
`(Circuit ID: <Circuit ID>)`
Preserve any existing description text. Before appending, remove any existing suffix matching `(Circuit ID:...)`, then trim surrounding whitespace. This makes reruns idempotent and replaces an old ID instead of accumulating duplicate IDs. If the description is empty after cleanup, set it to the suffix alone. Do not change an interface if its resulting description is already identical; log it as unchanged.
If duplicate CSV rows map the same order-independent circuit to different IDs, or the same endpoint to different IDs, print a warning and let the last row win. Keep enough row information to report the CSV line number for incomplete, conflicting, and unmatched rows.
### Plan-file handling and error recovery
Before importing the plan, check that the source path exists, is a regular file, is readable, and is non-empty; report failures clearly. Print the source path and byte size.
Try `Network(source_path)` first. If direct import fails, log the original error and try the Crosswork `mate_convert` CLI with `-plan-file <source> -out-file <temporary.pln>`, then open the converted file with `Network`. If both methods fail, raise a useful error containing both failures.
Try `network.write(destination_path)` first. If direct write fails, log the error, write a temporary `.pln` file with `network.write`, then convert it to the requested destination with `mate_convert -plan-file <temporary.pln> -out-file <destination>`. Remove the temporary staged file even if conversion fails. Remove the temporary converted input file after successfully writing the destination. Never delete or overwrite the source plan intentionally.
### Logging and command-line behavior
Print useful progress and audit messages: mapping file selected, number of valid mappings/endpoints loaded, plan validation, each updated or unchanged interface, missing interfaces, unmatched mappings, number of matched plan circuits, total descriptions changed, and unmatched mapping count when nonzero. Do not print sensitive data.
If fewer than two positional arguments are supplied, print concise usage showing `<source_plan> <destination_plan> [extra args...]` and exit with status 1. Otherwise run the operation with arguments 1 and 2 and optional upload directory at argument 6. Put executable behavior behind `if __name__ == "__main__":` and organize nontrivial behavior into small, documented helper functions.
Keep the implementation compatible with the Python runtime bundled with the target Crosswork Planning release. Use only the standard library plus the documented Crosswork OPM library and `mate_convert` CLI. Ensure the script is syntactically complete and handles filesystem, CSV, OPM collection, and subprocess errors with actionable messages.