| name | sw-kb-api |
| description | Query the SolidWorks knowledge-base catalog for categories, matching parts, complete published instructions, macros, known API errors, and lessons. Use after sw-pre-start and before any SolidWorks modeling or API work, for every part, assembly, drawing, repair, or model reproduction request. |
SolidWorks KB Lookup
Run $sw-pre-start first. Complete this lookup before CAD work.
Set KB_HOST from SW_KB_HOST; default to
https://sw-plugin.ideep.org. Use quoted curl shell calls only. Runtime
endpoints are public and use camelCase JSON.
1. Check health
curl -sS "{KB_HOST}/health"
If unreachable, tell the user Knowledge base is offline - proceeding without KB lookup, record the outage for session feedback, and continue from verified
engineering knowledge. Do not abort the CAD task.
2. Match a category
curl -sS "{KB_HOST}/api/categories"
Fuzzy-match the requested component against category name or slug. Save the
matching id as categoryId. If nothing matches, continue to the free-text
fallback in Step 4.
3. Match a part inside the category
curl -sS "{KB_HOST}/api/parts?categoryId={categoryId}&pageSize=100"
Optionally add a URL-encoded q parameter. Match active items by exact or close
partNumber, then by name. Save the best id as partId.
4. Load complete part detail
When partId is known:
curl -sS "{KB_HOST}/api/parts/{partId}"
Otherwise search globally:
curl -sS "{KB_HOST}/api/parts?q={encoded-name-or-number}&pageSize=20"
Fetch the best match's detail. Read every published instructions, macros,
knownErrors, and lessons item rather than relying on list summaries.
5. Apply the result
For a part with instructions:
- follow published instructions as the primary build guide;
- use a complete
isTemplate: false macro directly after replacing only
declared parameters with user values;
- adapt an
isTemplate: true macro to the current part;
- read all known errors before using any listed
swFeature and apply resolved
fixes proactively;
- treat every lesson
prevention as an active constraint;
- tell the user which part was found and how many macros are being used.
For a catalog part without instructions, apply its errors and lessons, explain
that no published build guide exists, and build from verified knowledge.
When no part matches, explain that the part is not yet in the KB, load the
global safeguards below, and build from scratch. Do not promise that feedback
will be sent; submission still requires consent.
6. Load global safeguards
Always run both calls, even if no part matched:
curl -sS "{KB_HOST}/api/errors"
curl -sS "{KB_HOST}/api/lessons"
Before every SolidWorks API call, cross-reference the method against global and
part-specific errors. When isResolved is true, apply resolution before the
call. Apply lesson prevention fields as rules, prioritizing critical and high
severity.
Cache and failures
Cache categories and global errors or lessons once per Codex task. Cache each
part detail once per build. Refresh only when the user explicitly requests it
or the task changes to a different part.
200: use the data.404: treat the resource as absent and continue.422: correct or simplify the query, then try the free-text fallback once.5xx or timeout: record the outage and continue without KB data.
