Documentation

1. Purpose

AdvisorAI is research software that supports the preparation of CNC milling programmes. From a part model (STL), a workpiece material and a machine, it produces a process plan and an ISO 6983 G-code programme. Each cutting-data value comes with the physical limit that determined it, so a planner can see why a value was chosen and what would allow a more productive regime.

It is intended for process planners, students and researchers in manufacturing engineering, and for evaluators of the underlying PhD research. It is not a replacement for CAM verification on the target machine.

2. Architecture

The deployment has three parts behind one Nginx reverse proxy on a single domain:

• Website (/) – static HTML/CSS pages built from site/src.
• Tool (/app/) – a Streamlit application (frontend/app.py) that imports the engine directly.
• API (/api/) – a FastAPI service (backend/) exposing the same engine for programmatic use.

The Python packages are engine/ (physics models, principled selection, planning, toolpaths, G-code, simulation, optimization), geometry/ (STL parsing and feature extraction), models/ (optional ML models), common/ (security and logging helpers shared by the tool and the API) and data/ (material, machine and tool databases).

3. Technology stack

4. Installation

Local development

git clone <repository-url> advisorai && cd advisorai
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env            # then edit .env
./scripts/run_local.sh          # API on :8000, tool on :8501/app
python3 site/build.py           # website into site/dist/

Open http://localhost:8501/app/ for the tool. To preview the website, run python3 -m http.server 8080 -d site/dist. The Launch the tool links point to /app/, which only works behind Nginx or the Docker set-up.

Docker

cp .env.example .env
docker compose -f docker/docker-compose.yml up --build

The compose file starts the API, the tool and an Nginx container on http://localhost:8080. Only Nginx publishes a port, and only to the loopback interface.

Production server

See docs/DEPLOYMENT.md in the repository. A single script installs everything behind Nginx with HTTPS on your domain.

5. Configuration

All settings come from environment variables. On the server they live in /etc/advisorai/advisorai.env, readable only by root (systemd passes the values to the services at start-up). The file .env.example documents every variable. No secret is stored in the source code.

6. Using the tool

1. Upload. Choose an STL file in millimetres (limit 25 MB), or click Use sample block. The file is checked for type, size, structure and triangle count before it is parsed.
2. Features. Review the detected surfaces, pockets, holes and thin walls.
3. Configure. Select the material and the machine. The selection determines the speed and feed bands, the specific cutting force, the spindle power and the machine's rigidity.
4. Process plan. Check the operations and the Governing limit column. Open Predicted process values for force, power, temperature, tool life and roughness per operation.
5. Physics, G-code, Validate. Inspect the detailed analysis, the generated programme and the simulation along the toolpath.
6. Export. Download the programme (.nc), the report and the JSON data.

Reading the governing limit

Checking your own G-code

1. Open Digital twin → Check my G-code. Choose Optimise my program or Compare programs.
2. Upload the part as STL (the finished part, in millimetres) and one to three programs (.nc, .tap, .gcode, .ngc, .cnc, .txt; up to 10 MB each), or load one of the examples.
3. Select the machine and the material. Under Stock, work origin and requirements you can set the stock size, enter the program zero, and set the target roughness and the allowed remaining stock.
4. Click Read programs. AdvisorAI detects the type (3-axis, 3+2 or turning) and the program zero, and lists the tools it found in the comments. Correct any tool marked assumed.
5. Click Optimise or Compare. The verdict, a side-by-side table, time and power charts, a map of remaining stock and gouges, and the findings with line numbers are shown. Re-tuned and AdvisorAI programs can be downloaded.

The re-tuned program keeps every coordinate, comment and block number; only F and S words change, and finishing moves never get a larger chip load than in your program. AdvisorAI's own program uses generic raster strategies: it is a safe independent benchmark, but a well-written contour program is often faster on simple prismatic parts, and the verdict says so.

7. API overview

The API is served under /api/ on the same domain and is rate-limited. Interactive documentation is disabled in production.

8. Reproducing the results

The tables and figures on the Results page come from two scripts in research/:

cd research
python3 case_study_models.py     # six-material case study
python3 p1s_comparison.py        # symmetric rule vs sequential rule P1-S

9. Security measures

A summary is given on the Privacy & security page. The full list and the threat model are in SECURITY.md in the repository.

10. Limitations

• No experimental validation yet. All predictions use provisional coefficients. The ISO 8688-1 calibration programme is designed but not carried out, so absolute values of force, temperature and tool life are indicative only.
• Tool life is very sensitive to its constants. A 10 % error in the Taylor constant changes predicted tool life by about 50 %. Compare regimes rather than trusting absolute minutes.
• Single thermal threshold. The same homologous-temperature limit applies to all material groups. Aluminium alloys are therefore often thermally limited, although their real limit is adhesion and built-up edge.
• Material coverage. Physics-based selection covers steels, stainless steels, cast irons, aluminium, titanium and nickel alloys. Other materials use handbook bands.
• Drilling uses handbook values; thrust force and torque are not modelled.
• Stability is a conservative estimate; stability lobes need a measured frequency response.
• G-code uses the basic ISO 6983 word set with FANUC-style reference return (G28). Always post-process and verify on the target controller before cutting.
• G-code check. ISO / Fanuc / Haas dialect only; no simultaneous 4/5-axis, macros, cutter-radius compensation in the control, or holder and fixture collisions. Height-map resolution is 0.2–0.4 mm (3-axis), voxels 0.35–1 mm (3+2) and 0.05 mm axially (turning); results near walls are accurate to about one cell. Tool data missing from the program are assumed and must be checked.
• Indicative costs only. Cost figures use generic hourly rates from the machine database (default USD 80/h) and catalogue tool prices. Economic tool life is not optimised; use shop-specific rates for real quotations.

11. Troubleshooting

• “This does not look like an STL file” – export again as STL (binary or ASCII). STEP files are accepted only by the API if the optional OCP libraries are installed.
• “The model has … triangles; the limit is …” – simplify or decimate the mesh in your CAD system.
• “Model larger than 10 m” – the file was probably exported in micrometres or inches; re-export in millimetres.
• An error with a reference code – the details are in the server log under that code. Quote it when you contact the project.