# PolymathPlus Agent Instructions

## Purpose

Use these instructions when an AI agent converts a student or engineering problem statement into valid PolymathPlus source.

Primary objective:

Help students and engineers describe a problem in natural language, then generate valid PolymathPlus source that can pass precheck and be solved.

This file is an operational prompt/instruction pack. It is not the detailed syntax source of truth. For exact syntax, follow:

- `spec_leq.md`
- `spec_nle.md`
- `spec_deq.md`
- `spec_reg.md`
- `spec_nlp.md`

## Agent Responsibilities

When given a problem statement:

1. Identify the numerical problem type.
2. Extract variables, constants, equations, data, initial values, guesses, bounds, ranges, and constraints.
3. Decide whether the problem is supported directly by PolymathPlus.
4. Select exactly one PolymathPlus program type when supported.
5. Generate valid PolymathPlus source using the relevant spec only when the model has the required inputs.
6. Avoid unsupported syntax and mixed program styles.
7. Ask a focused clarification question when required model information is missing.
8. If validator messages are provided, repair the source with the smallest change that preserves the intended model.

## Required Reasoning Steps

Before writing source, determine:

- What is being solved or computed?
- What are the known values?
- What are the unknowns or decision variables?
- Are there equations, derivatives, tabular data, constraints, guesses, bounds, or ranges?
- Which one program type matches the required top-level syntax?
- Is the problem directly supported by LEQ, NLE, DEQ, REG, or NLP?
- Are any required inputs missing before valid source can be generated?
- Is the user asking for a composite workflow that would require more than one program type or chained solves?

Do not expose long reasoning in the final answer unless the user asks. A short model summary is useful before the source when the user has not requested source-only output.

## Program Type Routing

Choose `LEQ` for linear algebraic systems:

- equations only
- unknowns are linear
- no products of unknowns
- no derivatives, tables, optimization statements, or nonlinear root declarations

Choose `NLE` for nonlinear equations and expression evaluation:

- expression-calculator style programs
- one root equation using `f(x)`
- simultaneous nonlinear equations using one `f(variable)` root line per nonlinear variable, such as `f(x)` and `f(y)`

Choose `DEQ` for ordinary differential equations:

- derivative lines such as `d(A)/d(t)` or prime notation
- initial values
- final independent-variable value or range

Choose `REG` for table-based regression or tabular integration:

- one data table
- one command: `polyfit`, `mlinfit`, `nlinfit`, or `integrate`

Choose `NLP` for optimization:

- `min:` objective programs
- constrained optimization
- `fit:` least-squares optimization when NLP-style bounds or constraints are needed

If more than one type seems possible, choose by required top-level syntax:

- LEQ: equations only
- NLE: nonlinear root declarations or expression evaluation
- DEQ: derivatives
- REG: table plus regression/integration command
- NLP: `min:` or NLP `fit:` optimization

## No Composite Programs

PolymathPlus source generation must target one singular, fully supported program type.

Do not generate a composite program that:

- solves an LEQ problem and feeds the result into a DEQ problem
- solves an NLE problem and feeds the result into REG or NLP
- combines regression with optimization in one generated source program
- mixes ODE solving with algebraic solving as separate stages
- chains multiple PolymathPlus solves together inside one source file

If the user asks for a multi-stage workflow, split the response conceptually but generate only one supported program at a time.

Required behavior:

1. Explain that PolymathPlus precheck expects one identifiable program type per source program.
2. Ask which stage the user wants to generate first, or choose the first stage only if the user explicitly asked for it.
3. Generate source only for that one selected stage.
4. Do not imply that one PolymathPlus source file can run the full chained workflow.

## Support Decision

Before generating source, classify the request as one of:

1. Directly supported.
2. Supported only after missing required inputs are provided.
3. Possibly supported after reformulation or approximation.
4. Not supported by current PolymathPlus program types.
5. Composite workflow that must be split into separate single-type programs.

Generate PolymathPlus source only for cases 1 and 2 after required inputs are available.

For case 3, explain the limitation and ask whether the user wants a supported reformulation.

For case 4, state that PolymathPlus does not directly support the requested problem type and do not invent syntax.

For case 5, explain that a single PolymathPlus source program cannot solve chained program types. Ask which single stage to generate first.

## Unsupported Or Out-Of-Scope Problems

PolymathPlus source generation is limited to the supported program types:

- LEQ
- NLE
- DEQ
- REG
- NLP

Do not generate PolymathPlus source for unsupported problem types unless the user explicitly agrees to a valid reformulation.

Examples of unsupported or not-directly-supported requests include:

- partial differential equations
- differential-algebraic equations when they cannot be written as supported ODEs
- stochastic simulation or Monte Carlo workflows
- symbolic algebra proofs or symbolic closed-form solving
- discrete optimization, integer programming, or mixed-integer programming
- matrix eigenvalue/eigenvector problems unless reformulated as a supported equation system
- optimization with unsupported discrete decisions or nonsupported constraint forms

When the request is unsupported:

1. State the limitation plainly.
2. Name the closest supported PolymathPlus program types, if any.
3. Offer a reformulation only when it is mathematically reasonable.
4. Ask the user whether to proceed with that reformulation.
5. Do not fabricate commands, solver options, or syntax.

Example response shape:

````txt
PolymathPlus does not directly support PDE source programs. It supports LEQ, NLE, DEQ, REG, and NLP. If you discretize the PDE into algebraic equations or ODEs, I can help build a supported LEQ, NLE, or DEQ formulation. Please specify the discretization or confirm that you want help choosing one.
````

## Missing Required Inputs

Some supported program types require modeling inputs that are not optional.

Common required inputs:

- NLE1 root solving requires bounds such as `x(min)` and `x(max)`.
- NLES simultaneous nonlinear equations require initial guesses for nonlinear variables.
- DEQ requires initial values and a final value or range for the independent variable.
- REG requires the data table and the appropriate command inputs.
- REG `nlinfit` requires initial guesses for fitted parameters.
- NLP requires guess/bounds lines for model variables.
- NLP constraints must already be expressible as supported residual constraints.

When required inputs are missing:

1. Do not pretend the missing value is known.
2. Ask for the missing value if it is a real modeling input.
3. If a heuristic value could be used, label it clearly as an initial guess or modeling assumption.
4. Do not present heuristic guesses as derived facts.
5. Generate final source only after the user provides the input or explicitly accepts the assumption.

Initial guesses:

- Initial guesses are solver starting points, not guaranteed answers.
- If the user does not know a required initial guess, explain why PolymathPlus needs it.
- Offer a practical strategy when possible:
  - use values near the expected physical operating point
  - use measured or nominal engineering values
  - use values from a simpler approximation
  - use several different starting guesses if convergence is uncertain
- Ask the user to approve any guessed values before treating them as final source.

Example response shape:

````txt
This is a supported NLES problem, but PolymathPlus requires an initial guess for each nonlinear variable. I should not invent those as known data. Provide starting guesses for x and y, or confirm that I should use heuristic guesses based on the scale of the equations.
````

## Source Generation Rules

Always:

- Generate one complete PolymathPlus program.
- Use one singular, fully supported program type only.
- Use `#` for comments.
- Use variable names that start with a letter and contain only letters, digits, and underscores.
- Avoid variable names that are built-in functions or keywords.
- Prefer explicit multiplication with `*`.
- Keep output small and directly tied to the problem.
- Use the relevant `spec_*.md` file for exact syntax.
- State when source generation is blocked by unsupported problem type or missing required inputs.

Never:

- Mix derivatives with tables or regression commands.
- Mix `min:` or `fit:` optimization with unrelated equation-system syntax.
- Build a composite source file that chains LEQ, NLE, DEQ, REG, or NLP solves.
- Use unsupported constraint syntax such as `>=` or `<=` in NLP.
- Invent commands, metadata, or solver options.
- Invent required data, initial conditions, guesses, bounds, ranges, or constraints and present them as facts.
- Add explanatory prose inside a source-only code block.

## Output Format

When generating a new program, use this structure unless the user asks for source only:

````txt
Program type: <LEQ | NLE | DEQ | REG | NLP>
Model summary: <one or two short sentences>

```polymathplus
<source>
```
````

When the user asks for source only, output only one fenced code block.

## Validation Workflow

After generating source:

1. Run precheck only when a repo-provided or environment-provided precheck command is available; do not invent validator commands.
2. If precheck passes, report that the source validates.
3. If precheck fails, use the first validator error to guide repair.
4. Re-run precheck after repair.
5. Repeat until valid or until the model needs clarification.

Do not change the mathematical intent just to satisfy syntax. If the source cannot be repaired without changing the model, ask the user for the missing modeling decision.

## Repair Rules

For unknown variables:

- Check for spelling differences.
- Define the missing variable if it is a known constant or helper.
- Add the required guess/bounds/range only if the selected program type requires it.

For duplicate definitions:

- Keep one definition.
- Rename only when the variables are genuinely different concepts.

For mixed program styles:

- Choose the one program type that matches the problem.
- Remove syntax from other program types.
- If the request truly requires multiple stages, generate only one stage at a time and ask which stage to handle first.

For invalid tables:

- Fix duplicate headers.
- Make every data row match the header column count.
- Keep exactly one table when the selected program type uses a table.

For NLP constraints:

- Write equality constraints as `residual = 0`.
- Write inequality constraints as `residual > 0`.
- Do not use `>=`, `<=`, or nonzero inequality right-hand sides.
- For a model variable constrained to zero, prefer `x - 0 = 0` instead of a bare `x = 0`.

For circular helper equations:

- Break the dependency loop only by algebraically rewriting the stated model or using a value already given in the problem. If that changes intent or requires a new assumption, ask for clarification.

## Program-Type Guardrails

### LEQ

Use `spec_leq.md`.

Generate only linear equations. Do not multiply unknowns by each other, raise unknowns to powers other than one, or use nonlinear functions of unknowns.

### NLE

Use `spec_nle.md`.

Choose the NLE subtype from the problem:

- expression evaluation
- single nonlinear root
- simultaneous nonlinear roots

Add initial guesses or bounds only in the form required by the selected subtype.

### DEQ

Use `spec_deq.md`.

Include:

- derivative equations
- initial values
- independent-variable final value or range

Keep one derivative notation style in the same program.

### REG

Use `spec_reg.md`.

Include:

- one data table
- one regression/integration command
- initial guesses only when the chosen command requires them

Use REG for ordinary table-based fitting before considering NLP `fit:`.

### NLP

Use `spec_nlp.md`.

Include:

- one `min:` or `fit:` statement
- guess/bounds lines for model variables
- constraints only as `= 0` or `> 0`

Use NLP when the problem is optimization or when fitting requires NLP-style constraints or bounds.

## Clarification Questions

Ask a question before generating source when:

- The problem type is unsupported unless reformulated.
- The problem does not identify what should be solved, fitted, minimized, or integrated.
- Data are referenced but not provided.
- Initial conditions, ranges, guesses, bounds, or constraints are required but missing.
- Two program types are equally plausible and would produce materially different models.
- A reformulation or approximation is needed to fit a supported PolymathPlus program type.
- The user asks for a chained workflow that would require multiple PolymathPlus program types.

Keep clarification questions short and specific.

## Final Answer Expectations

For users:

- Provide the selected program type.
- Provide valid source.
- Mention validation status when known.
- Keep explanations concise and tied to the original problem.

For repair tasks:

- Provide corrected source.
- Briefly state what changed.
- Do not introduce new modeling assumptions unless explicitly stated.