Aner in VS Code

Use VS Code to edit .aner source files and work in .anernb notebooks with code, Markdown, images, and saved results. The Aner extension supplies the editor features; an installed native Aner executable runs your programs.

This guide describes the current extension, 0.1.35. Public packages and supported platforms depend on the release. Check installation and availability, then use the binary and editor extension versions recommended together by that release.

Install the editor extension

1. Install the native Aner package for your operating system and architecture by following the installation guide.
2. Download the VSIX supplied with that release, or find it in the package's editor/ directory when included.
3. In VS Code, open Extensions, choose … → Install from VSIX…, and select the supplied file.
4. Run Developer: Reload Window from the Command Palette after installing or updating the extension.

The editor package described here is named aner-language-0.1.35.vsix. If the code command is available, you can also install it from the folder containing that downloaded file:

code --install-extension aner-language-0.1.35.vsix --force

Use the filename supplied by your release when it differs. These instructions do not assume an extension Marketplace listing. The same VSIX supports VS Code on macOS, Windows, and Linux; the native executable must match the machine where execution happens. In a remote VS Code session, install the matching native executable and workspace extension on that remote machine.

Choose the installed executable

Open VS Code's integrated terminal and check:

aner --version

If that command works and the extension has access to the same PATH, it can find the installed executable. For a predictable installation, open Settings, search for Aner: Notebook Executable, and set the full path to your installed aner executable. The setting key is aner.notebook.executable.

For example, if this is the actual location of your Linux installation:

{
    "aner.notebook.executable": "/path/to/aner/bin/aner"
}

On macOS, select the executable inside your installed Aner package in the same way. On Windows, select aner.exe; backslashes in JSON are escaped:

{
    "aner.notebook.executable": "C:\\Users\\you\\Apps\\Aner\\bin\\aner.exe"
}

Replace these example paths with your own installation location. An explicit setting takes priority over automatic discovery. You can set it for one workspace when different projects use different Aner releases. After moving or updating an installation, update the path and restart any running notebook session.

Write a source program

Open your own project folder with File → Open Folder…, create hello.aner, and save:

let message = "Hello from Aner"
print(message)

The language mode in the lower right corner should read Aner. If it does not, click the language mode and choose Aner. A project can also explicitly associate its source files:

{
    "files.associations": {
        "*.aner": "aner"
    }
}

From the integrated terminal, with the project folder as the current directory:

aner check hello.aner
aner run hello.aner

The first command checks the file without running it. The second prints Hello from Aner. Errors identify a source location when applicable. The editor's syntax colors do not replace static checking.

Create a notebook

Run Aner: New Notebook from the Command Palette. Save it as experiment.anernb inside your project folder. If prompted for a kernel, choose Aner — notebook.

Put this in the first code cell and run it:

var a = 10

Put this in a second cell and run it:

a = a + 5
print(a)

The second cell prints 15. New notebooks use shared variables, so values, imports, and definitions can remain available between cells. No fn main() is needed. Add Markdown cells for explanations, tables, or images. Choose Run All to execute the code cells in order.

Notebook execution requires a trusted workspace. Only trust a folder when you are comfortable executing its code. Viewing and editing notebooks remain available without trust.

To work through supplied examples, open the folder containing their examples/ directory. Start with shared variables, the concise Iris classifier, or concise object methods. Keep the example files and data paths together.

State, modes, and restart

Use Aner: Use Shared Variables for experiments split across cells. Use Aner: Use Independent Programs when every cell should run as a separate script or complete main program. The mode belongs to the whole notebook and is saved with it; selecting a kernel does not change it.

Changing modes clears live state and never reruns earlier cells. Aner: Restart Notebook Session also clears state. Run the defining cells again before using their values. Restart before changing or rerunning a function or class definition; those definitions cannot currently be replaced within a live session.

Syntax and type errors preserve earlier successful state. An execution error, Stop, timeout, notebook closure, or extension reload clears the session. Stop cancels execution; it is not a debugging pause. Saved notebook outputs may still be visible afterward, but saving or reopening does not restore variables. See notebook behavior and limits for the complete rules.

Development inspection

Production is the default runtime mode. Choose Dev in the notebook toolbar, rerun setup cells, then choose Inspector to see bounded typed globals, named observations, collection/object trees and reference diagrams, and captured loss after a cell completes. This setting is separate from shared variable/independent program execution. Switching Dev/Prod cancels work and clears state; selecting the already active mode keeps the session. Save the notebook to retain its runtime mode metadata.

Use Aner: Open Development Training Report for recorded topology, activations, and available gradients from a completed training cell. A retained training view labels its originating execution as historical; the variable table describes the current completed cell. Source edits mark observations stale, and restart, Stop, timeout, runtime failure, or switching modes invalidates live state. Set aner.notebook.developmentValues for bounded raw tensor/neuron values; it defaults to false.

For a plain source file, run aner FILE.aner --dev NEW_DIRECTORY in the terminal and open inspection.html. Production disables automatic recording; aner FILE.aner --prod makes the default explicit. See the mode guide, the development neural notebook, and the linked list development notebook. These views observe completed executions; streaming during a cell and pause/step debugging remain future work.

Inspect a recorded training report

With an Aner notebook active, click Open training report in its toolbar or a code cell's status bar, or run Aner: Open Training Report from the Command Palette. On first use, select an existing index.html or trace.json from an Aner visual report directory. Both files must remain in that directory. The interactive report opens beside the notebook, with recorded topology, loss chart points, and available tensor values and gradients.

Generate the report first using the native CLI and a new output directory. For the detailed Iris notebook, run this from the folder containing examples/:

aner run examples/neural_iris.aner --debug-viz reports/iris-notebook --debug-values

Then select reports/iris-notebook/index.html or trace.json. Open training report remembers the association for this notebook in the workspace and reuses it later. Run Aner: Choose Training Report to select another report. The association is not stored in the notebook file.

Opening a report does not execute cells, generate captures, or display live session variables. Its observations are historical, and the extension does not verify that the selected report matches the notebook's current source. After changing a program, generate a new report and choose it explicitly. See visual training reports for the controls, capture limits, and standalone browser workflow.

Colors and editing

Choose Preferences: Color Theme to switch between light and dark themes. Aner uses the active theme's syntax colors for keywords, types, functions, strings, numbers, and comments.

The extension supports line comments, matching brackets, automatic closing pairs, and snippets. Use Insert Snippet or type a snippet prefix such as fn, let, class, importdataset, or nnsequential, then select a suggestion. Syntax highlighting is available for source files and notebook code cells.

Collection snippets and signature help

Extension 0.1.31 provides list, dictionary, set, collections, and listsort snippets with valid mixed value examples. Use Insert Snippet, or type a prefix and invoke Trigger Suggest. The listsort snippet demonstrates stable ascending numeric and String sorting. The sort() signature includes its compatible type rules, O(n log n) comparison count, and O(n) auxiliary space. These built in types need no import. Run the collection example or notebook, and read the separate Dictionary, List, and Set references for API and time/space complexity.

When entering a built in call, signature help shows its parameter labels, return type, time complexity, auxiliary/result space, and important rules such as index bounds or supported key types. It appears after (, ,, or :, or use Trigger Parameter Hints (usually Ctrl+Shift+Space; Cmd+Shift+Space on macOS). Collection receiver recognition includes constructor bindings, explicit annotations, parameters, checked cast<List/Dictionary/Set> expressions, copies, and supported method chains. Unknown or custom same named methods do not receive guessed native collection signatures. This helper is not a language server or a substitute for aner check.

Rebuild or install the compatible native interpreter as well as updating the VSIX. An older binary cannot execute new collection APIs. After replacing the executable, restart existing notebook sessions before using them.

Neural and development helpers

Extension 0.1.31 includes devcapture and devenabled for named observations and guarded diagnostic work, nndenseweights for custom finite Dense weights/biases, mlsave/mlload for fitted checkpoints, and mlwarmstart for continued training. Import aner.dev, aner.nn, or aner.ml as appropriate. The snippets use real Aner APIs and are checked against the native interpreter.

Signature help covers the custom Dense overload, pre fit network/pipeline summaries, optional loss/SGD optimizer configuration, detached fitted weight/bias extraction, checkpoint save/load, warm starts, and development capture contracts. Checkpoints require a new file; loading validates the saved architecture, fitted parameters, scaler, schema, and bounds. See the runnable model state example and API/complexity documentation. Update the native executable as well as the extension before using these APIs.

Aner snippets and AI suggestions

Inline AI suggestions may guess another language's syntax. For example, def, @head, nil, and end are Ruby syntax, not Aner. Keeping AI previews enabled does not make those suggestions type checked. Dismiss an unrelated preview with Escape and select an Aner snippet instead.

With editor extension 0.1.20, start in an empty .aner file, type linkedlist, then invoke Trigger Suggest and choose Basic linked list. Alternatively, run Insert Snippet from the Command Palette and choose Basic linked list. It inserts a runnable Node and LinkedList example with prepend, append, and len. Tab moves between the Node and LinkedList name placeholders. The smaller nullablefield, newnode, and traverselist snippets cover fields, construction, and traversal; existing class, method, setter, and unwrap templates remain available.

The project puts Aner snippets at the top of the suggestion list without changing inline AI settings. These templates use fn, braces, typed links, null, named constructor arguments, and direct access after null checks. Check saved code with aner check FILE.aner. See the basic linked list example and Aner's object model. The templates are checked by running expanded snippets with the native interpreter. Extension 0.1.22 simplifies guarded traversal and includes mixedlist, which creates a single list holding different value types without generics; anyfield, typeof, and cast support dynamic data fields and checked retrieval. Rebuild the native interpreter too; updating the extension does not add Any or null check narrowing to an older executable.

When asking an AI assistant for Aner code, provide a valid .aner example and the language reference as context, and explicitly request Aner syntax. This helps supply context but cannot guarantee valid generated code.

The current extension provides read only variables and training inspection after completed development cells. A language server, streaming training charts, and pause/step debugger remain future work. Program output, dataset/model summaries, and separately recorded training reports remain available alongside the Dev Inspector.

Troubleshooting

The extension runs with VS Code's own runtime and the installed native Aner executable.

Typed array help

Extension 0.1.31 includes Array<T> and DynamicArray<T> snippets with required dtypes and explicit size/capacity. Signature help restricts methods to the actual dtype/family and documents sorting, automatic sorted search, numerical operations, growth, and time/space costs. In notebook Dev mode, Inspector displays array dtype, logical length, reserved capacity, sorted status, and bounded element previews. See Array, DynamicArray, and the array notebook.

Multidimensional array help

Extension 0.1.31 includes NDArray syntax, verified matrix/broadcast snippets, typed signatures, and method time/space complexity. Inspector shows shape, element strides, row major previews, and matching storage IDs for shared fixed reshapes. It distinguishes these from one dimensional binary/linear search information. See the multidimensional reference and notebook.

Neural training and hardware help

Extension 0.1.31 includes signatures for Adam, seeded/Xavier/He Dense initialization, fixed epoch progress, measured training duration, native CPU/CUDA Float64 or Float32, Metal/MPS Float32, preserve/adapt/fast execution profiles, synchronization, and backend capability queries. Helpers explain defaults, time/space complexity, checkpoint continuation, and unsupported device errors. Inspector shows the resolved execution profile, including requested and effective precision, policy, computation/accumulation precision, and reason. Tensor previews show actual Float64/Float32 precision, CPU/MPS/CUDA placement, and native provider; completed training observations show elapsed/estimated remaining time and omitted events. Verified nnprofile, nncuda64, and nnpolicy snippets add portable execution configuration, strict Float64 CUDA parameters, and per classifier precision policy. Existing nngpu, nndtype, and nnsync cover explicit Float32 placement, detached conversion, and device observation. Helpers explain CPU Float64 fallback for a preserve request on Metal/MPS and intentional Float32 selection without promising speedup. Inline AI previews stay enabled. See Tensor devices and performance. Use the neural workflow, complete research source, and research notebook. Run Developer: Reload Window after installing the updated extension.

Audited mini batches and larger notebook cells

Extension 0.1.31 recognizes DatasetPartition, DatasetFolds, DatasetBatches, TrainingConfig, and Optimizer. Hints cover protected roles, stratified/group aware partitions, fold audits, lazy batches, Xavier MLP construction, keyed Adam/SGD updates, and fixed epoch training with validation and optional best epoch selection. Variables declared by for batch in data.batches(...) receive Dataset hints within that loop. Use datasetpartition, datasetgroups, datasetbatches, nnminibatch, and nnoptimizer for verified templates. Dataset partitions and neural workflows define correctness and Big O bounds.

The Inspector charts measured online training loss, held out validation loss, and validation accuracy when those observations are supplied. The table retains the phase, cumulative update count, actual batch size, elapsed time, and device. Manual observations without counts display unknown rather than inventing a count. Observations appear after the cell completes.

For a longer training cell, change aner.notebook.timeoutMs before execution:

{
    "aner.notebook.timeoutMs": 600000
}

The default is 120,000 milliseconds. The resource setting accepts integers from 1 through 86,400,000 and applies to subsequent cells in either execution mode. Changing it retains current shared variables; an active request keeps its original deadline. An actual timeout terminates that notebook's native process and clears variables. Rerun setup after a timeout. The timeout is an execution bound, not a training completion estimate.

Native parallel computing help

Extension 0.1.33 recognizes ParallelContext, ParallelResult and aner.parallel. Typing parallel. offers verified module members; a result with a known native type offers estimate, hits, samples, workers, seconds, cancelled and summary. Shadowed names and unknown custom receivers do not receive guessed native methods. Signature help retains each actual overload, its named arguments, CPU allocation rules and time/space complexity.

Use importparallel, parallelmc and parallellocal for verified native CPU templates. The simple simulation uses automatic local allocation; the explicit context exposes worker and chunk control. Native parallel computing documents source, terminal jobs, private worker configuration and current limits. parallelneural, parallelneuraldevice and datasetsynthetic add verified protected Dataset Dense training, strict replica placement and bounded source generation. parallel.device and every parallel.fit overload show exact labels, precision and time/space bounds. The fitted result retains existing evaluation/checkpoint hints. Distributed neural training distinguishes CPU canonical updates from actual replica forward/backward work. Direct GPU collectives and model sharding remain planned. Existing inline AI previews stay enabled.

Language model and credential helpers

Extension 0.1.34 recognizes aner.llm, aner.secrets, LLMClient, LLMMessage, LLMResponse, and SecretRef. Typing llm. or secrets. offers exact native members. A receiver with an inferred LLMClient type offers generate, chat, provider, and model; an LLMResponse offers text, model, finish_reason, input_tokens, and output_tokens. Helpers retain overloads and named arguments, document provider neutral controls and request bounds, and distinguish Aner client complexity from remote inference. Unknown or shadowed receivers are not assigned guessed native methods.

Verified snippets include llmlocal, llmchat, llmcloud, llmvllm, llmclass, and secretref. Inline AI previews remain enabled. Credential snippets insert a reference label or environment variable name, never a key literal. Configure keys in an interactive terminal through aner secrets set NAME; a notebook output or text field is not a credential prompt. See Language model connections, Credentials, and the local request notebook.

LLM handles are opaque during development inspection. Explicit prompt Strings and text read through answer.text() retain ordinary String visibility and may appear when printed or captured. The same source and configured provider execute in development and production; observation does not change inference settings. Update the native executable and the extension together, then reload the editor window.

Native model API helpers

Extension 0.1.35 recognizes aner.api and the opaque APIApp type. Typing api. offers exact native app, model, language model, bind, authentication, TLS, limits, rate limit, OpenAPI and foreground serving methods. An inferred APIApp receiver offers immutable builders with the receiver parameter omitted. Helpers explain loopback defaults, the external TLS and bearer requirement, fixed input schemas, bounded transport, and inference deadlines that cannot forcibly preempt CPU or GPU computation.

Verified snippets are apilocal, apicheckpoint, apiauth, apitls, and apillm. They retain credential references and load models before serving. Prepare the checkpoint and certificate files before running examples that require them. aner check validates source without opening a listener. Run the API in a standalone program; serve blocks a notebook interpreter cell until stopped. Inline AI previews remain enabled. See Model inference APIs for request contracts, authentication, deployment, and complexity.