AI Assistant

Aptli's AI assistant accelerates data discovery across your asset and operations data. Ask a question in plain language — "show me cable runs near the substation" or "which sites are below minimum stock?" — and the system searches your map features, work orders, and database before calling the AI provider. You can also draw a lasso area on the map to query everything within it, and the AI helps map column headers when importing CSV or XLSX files.

The AI toolbar is the primary way to ask questions about your data. It appears in the top navigation bar (desktop) and is accessible from the map page on mobile.

Keyboard shortcut: Enter (when no input field is focused) opens the AI input immediately
Click: tap the AI icon in the toolbar
Map page: available as a persistent input at the top of the map sidebar

How It Works — Tiered Search

When you submit a query, the system tries three tiers in sequence, stopping as soon as it has a confident answer:

1. Local  → Search features already loaded in the map (instant, no server call)
           → Returns matching points, lines, polygons by name / property value
           ↓ No match?
2. Server → Query the database for features, work orders, reports, users
           → Full-text + structured filter
           ↓ Still no match, or query is a sentence?
3. AI     → Send query to the configured AI provider
           → Provider interprets the question and returns structured data

Sentence detection determines whether a query should skip straight to tier 3. Queries like "show me all cable runs near the substation" are detected as natural language and sent to AI directly; short queries like "cable 42" go through local and server first.

What You Can Ask

Feature lookups: "Pole A-123", "all inactive sites", "linestrings with capacity > 100"
Work status: "open work orders assigned to Sarah", "reports submitted this week"
Location queries: "features near Main Street and 5th"
Aggregation: "how many tasks are overdue in Zone B"
Properties: "resources where unit of measure is meters"

Rate Limiting

Each user is subject to a per-hour AI query limit (default 20, configurable by admin in AI Settings). Local and server searches do not count against this limit — only tier-3 AI calls do. The toolbar shows remaining quota when you approach the limit.

Provider and Model Settings

Admins configure the AI provider and model in Admin → Settings → AI. Contact your admin if AI responses are unavailable or appear degraded.

AI Lasso Mode

The AI lasso is a map tool that lets you draw a freehand area and ask the AI about everything within it.

Activating Lasso Mode

Open the map
Select AI Lasso from the mode selector (the orange polygon icon in the map toolbar)
The cursor changes to a crosshair

Drawing a Query Area

Click (or tap) to place the first point
Continue clicking to trace the area of interest
Double-click (or tap the starting point) to close the polygon
An orange polygon appears on the map; the AI query panel opens automatically

The Query

The lasso collects:

All Aptli features (points, lines, polygons) inside the drawn area
OSM / Overpass context for the same area (road names, land use, infrastructure types)

This combined context is sent to the AI with your question. You can ask:

"What infrastructure crosses this block?"
"Summarise the work orders covering this area"
"Are there any features without an assigned maintenance zone?"
"Which sites within this polygon are below minimum stock?"

Editing the Polygon

The orange lasso polygon stays editable after the first query:

Drag vertices to resize
Click an edge to add a new vertex
Re-submit the query to refresh results with the new shape

Clearing the Lasso

Click the Clear Lasso button (×) or switch to any other map mode. The orange polygon is removed.

Schematic AI Context

On the schematics page, a dedicated AI context builder summarises the open diagram and sends it to the AI for reasoning.

What It Does

The AI builds a structured summary of the diagram that includes:

Node types and counts (how many transformers, splitters, endpoints)
Edge types and connections (which nodes link to which)
Capacity and load annotations (if present in schematic properties)
Orphaned nodes (nodes with no connections)

This structured summary is sent as context with your query, so you can ask:

"Which segment has the highest load?"
"Find nodes with no downstream connections"
"What would happen if Node 7 fails?"
"Summarise the path from the head-end to endpoint E-42"

Accessing Schematic AI

Open a schematic from the schematics page or from a feature's relationship panel
The AI input appears in the schematic toolbar (top-right of the diagram view)
Type your question and press Enter

AI Column Mapping (CSV / XLSX Import)

When you import a CSV or XLSX file using the Data Transfer panel (or the bulk import workflow), the AI assists with mapping your file's column headers to Aptli's field schema.

How Column Mapping Works

After uploading a file:

Aptli reads the first row (headers) from the file
For each header, the AI suggests the best matching Aptli field (name, latitude, longitude, resource, site, status, etc.)
Matched columns appear pre-filled in the mapping table
Unmatched columns are flagged for manual assignment or skipped

Reviewing and Confirming

The mapping table shows:

File Column — your original header name
Mapped Field — Aptli's suggested field
Sample Values — first 3 rows of data for that column

You can:

Accept the suggestion (click checkmark)
Change the mapping (dropdown)
Skip the column (toggle off)
Mark as a custom property (stores in properties object)

Applying the Import

Once mapping is confirmed, click Apply. The system:

Processes each row against the confirmed mapping
Creates or updates records in the target model (features, resources, stock items, etc.)
Reports a count of created / updated / skipped / failed rows

Supported File Types

Type	Notes
`.csv`	UTF-8 or UTF-8-BOM; first row = headers
`.xlsx`	First worksheet only; rich-text cells flattened to plain text

For GIS-specific formats (GDB, SHP, GeoPackage, DXF, DGN), see GIS File Imports — those go through a different pipeline.

Tips and Limitations

AI queries require network access. Tier-3 AI calls go to an external provider. Local (tier 1) and server (tier 2) searches work offline.

AI does not modify data. All AI outputs are read-only. Saving, creating, or deleting records always requires an explicit user action.

Context window. Very large schematics or feature sets may be summarised before being sent to the AI. If results seem incomplete, try narrowing the lasso area or being more specific in your query.

Provider outages. If the configured AI provider is unavailable, tier-3 searches fail gracefully with an error message. Tier 1 and 2 still work.