How Forma works, in detail.

Getting started

Forma turns a report design you already have, or one you describe in words, into a DevExpress .repx file, with a written specification and a mockup read off it and a Preview that prints it as DevExpress would. The whole loop happens in your browser.

Your API key

Forma ships with no API key and cannot be given one. There is no shared quota and no application key behind the scenes. You supply your own, and your browser calls Google directly with it — it never passes through Forma's server, because there is no generation endpoint there to pass through.

Getting a key

1 · Google AI Studio

Sign in at aistudio.google.com/apikey and create a key.

2 · Open the workspace

Without a key the message box is locked, and its button opens Settings at the key; Settings is also under Configure in the sidebar.

3 · Paste it

Into Settings → Gemini key, where it takes effect as you paste it. Check key sends a single one-token request, which also works out which model your key can reach.

Where it is kept

The key is never written to disk in plaintext, on any tier.

Working copy

Session storage. The browser erases it when the tab closes — a guarantee a page-unload handler cannot make, because it never fires on a crash or a force-quit.

A new tab

A Forma tab you open while another is open gets the key from it, inside this browser, so you do not paste it again; when the last Forma tab closes, it is gone. Settings, under Gemini key, turns this off.

Durable copy

Opt-in, encrypted. If you want the key on more than one machine, it is encrypted in your browser under a passphrase you choose and only the ciphertext is uploaded. Requires a signed-in account.

Legacy plaintext

An older build kept the key unencrypted in local storage. That entry is now deleted automatically every time the app loads.

Choosing your AI

Gemini designs your reports unless you choose another AI, under Settings → AI. Whichever you choose, OCR and Forma's own model work beside it on every request, and every choice can be used for free.

Automatic

Google Gemini with your own free key. Forma finds the models the key can reach and uses the best one that answers; the box offers Fast and Balanced beside Auto.

Local AI

Ollama or LM Studio on this computer: free, unlimited and private, since nothing leaves the machine. The server address starts at http://localhost:11434/v1, where Ollama answers; LM Studio answers at port 1234. Name the model, or Find models lists what the server has.

OpenRouter

OpenRouter's free models, with a key of your own from openrouter.ai. Find free models lists them once the key is in. Free models have daily limits, and their providers may log requests. The key is held in your open Forma tabs only, as the Gemini key is.

A vision model

Optional, on Ollama or LM Studio: Forma's own vision model reads a picture's layout and OCR places its words in it. The AI designs from that draft, and if it cannot answer, the draft is your report.

Your account

You do not need one. Forma works fully signed out — your projects are kept in this browser and are still there when you come back. An account adds three things: your projects and their revisions follow you to another machine, you can share a report by link, and you can keep an encrypted copy of your API key so you are not pasting it in again on every device.

Creating one

With Google

One click, nothing to remember. This is the quicker route and the one to prefer unless you have a reason not to.

With an email address

An email and a password of at least eight characters. A name is optional — leave it blank and your email is used instead.

Either way

Signing in never asks for your API key, and your key is never part of a saved project.

Forgotten password

Enter your email address on the sign-in screen and choose Forgot password. A reset link is sent if an account exists for that address.

Managing the account

In the workspace, open the account disc at the foot of the rail and choose Account settings. The dialog lists its sections on the left, as Settings does: Profile, then Password and Email address on an account with a password, then Delete account.

Profile

The address you are signed in with, a reminder with Send it again until it is verified, and your display name, which you can change at any time. Two characters or more.

Password

Changing it asks for the current one first, and for the new one twice — a typo would otherwise set a password you do not know, and you would find out at the next sign-in somewhere else. Accounts created with Google have no password to change — Google keeps that.

Email address

A confirmation link goes to the new address and the account moves only when you open it, so a typo cannot lock you out. Your current password confirms the change, typed in that section.

Deleting the account

Type DELETE and, on a password account, your password. Removes your saved projects with their revision history, every report you shared (its link stops opening), and the encrypted copy of your key. Reports kept only in this browser are not touched. It cannot be undone.

Signed in somewhere you should not be

Change your password: every other session ends within the hour, as Firebase ends them when a password or an address changes. An account that signs in with Google ends its sessions from its Google Account's security page. If you cannot get in to do either, write through the contact page and the account can be suspended, which ends its sessions, until it is yours again. Forma offers no second factor: Firebase's needs a paid upgrade, and Forma stays free.

Each section asks for its own password

A password typed under Password does not arm the delete button or confirm an email change: each section reads its own box, whichever section you typed in last.

What you can upload

Files are prepared in your browser before anything is sent — resized, rendered, parsed. Anything that cannot be used is named on screen rather than skipped silently.

PNG · JPG

Screenshots, exports and phone photos. Large images are downscaled to a 2048px long edge and re-encoded; anything already smaller is passed through untouched.

PDF

Up to 8 pages per file. Each page is rendered at roughly 250 DPI and its text layer is extracted in the same pass. Pages beyond the cap are reported.

.repx

Read as text and validated as XML in your browser before a request is spent, then sent as exact markup so a refinement edits what is really there.

Per request

Up to 12 attachments, each up to 20 MB.

Why a PDF beats a screenshot

A digital PDF already contains every string and its exact position. Forma reads each page twice — once as an image for borders, fills and logos, once as text for content and coordinates — and converts every position from PDF points into the report's own grid before sending.

612 × 792 pt  →  × 100 / 72  →  850 × 1100 report units
y_top = pageHeight − (baseline + height)

Running and refining

Most reports take two or three passes. The first gets the structure, and the ones after it fix the parts that came out wrong. Nothing is thrown away between them.

While it runs

Three dots

While Forma works, the reply shows three dots and every step happens behind the scenes, as in the chat apps you know. The first request of a session is slower than the rest because it also works out which model your key can reach.

Stop

The send button becomes Stop while Forma works, and aborts the request in flight; Escape in the box does the same.

The queue

What you send while Forma works waits in a queue over the box. Steer sends one now and changes the request under way; Stop pauses the queue, and Resume sends it on.

Reading the result

One request comes back as the .repx, and the specification and the mockup are read off it, so the three always agree.

The specification

A component inventory in markdown, read off the .repx — every element, where it sits, its type, its font and its borders. Useful on its own as the written brief you would otherwise have produced by hand, and worth reading first: if the specification describes the wrong thing, the layout will too.

The mockup

The layout drawn at true proportions, on a sheet that stays white in both light and dark themes because a printed report does. Check positions and alignment here rather than in the XML. Charts are stylised and gauges and barcodes are marked out but not drawn — see Supported controls for what that means.

The XML

The DevExpress file itself, syntax-coloured with line numbers and a copy action. Covered in The .repx file.

The Preview

The report paged as DevExpress prints it, over test data Forma can make. Drag or retype a control here, and export it as PDF (with an outline, a password, or as PDF/A), Excel, CSV, Word, RTF, HTML or a picture, all in your browser.

Asking for changes

Say what is wrong rather than describing the whole report again. With a report open, the chat reads its outline and does one of three things: answers a question about it; edits the file in place (a move, a font, a colour, a border, a number format, a binding, a page number, a table's row or column, a duplicate, a band's height); or, for what an edit cannot reach, asks before redesigning it. Each reply lists what changed, with Undo and Redo, and "undo that" in the chat takes the last change back.

Name the region

"The totals block should sit under the table, not beside it." Pointing at a part of the page works better than restating the requirements.

One thing at a time

A short instruction is easier to apply correctly than five bundled together, and it is easier to tell which one did not take.

Say it is a table

If a grid came back as separate labels, ask for that region to be one table with rows and cells. It is the most common single correction.

Questions stay questions

A question is answered as a conversation, not with a new report. Asking "what does ReportUnit mean?" costs you a sentence; describing a report is what builds one.

The workspace

Laid out as the chat apps you know: a sidebar on the left, the report filling the rest, and one box at the foot that takes every request — a file, a description, a question or a change.

The sidebar

New report

An empty workspace whose home asks What report shall we make?, with six starting points — invoice, customer list, sales by region, employee directory, purchase order, inventory status — that fill the box for you, and your five most recent projects.

Search and Saved projects

Find a project and reopen it where you left it.

Revisions, Batch, Report library

Three panels: the versions of this report, many files at once, and reports whose style to match.

Configure

Opens Settings: General, AI, Gemini key and Memory.

Your account

The disc at the foot: Account settings and Sign out, or Sign in. Ctrl+B shows or hides the sidebar; on a phone it is a drawer.

The report

Five views

Mockup, Preview, Data, Spec and REPX, all read off the one file. Zoom with + and −, and Ctrl+\ clears the screen of everything but the report.

On the Preview

Click a control to select it, drag it or nudge it with the arrows, double-click to retype it, and right-click for its menu. Ctrl+L puts the selection in the chat, so a request can name it.

The project menu and the title

The button before the project's name renames, duplicates, archives or deletes a saved project. The pin beside the name pins it on this device. Each of the workspace's options has one place: projects and Settings in the sidebar, Share and Export in the bar, help, the shortcuts and the command menu in the ? at the corner.

Save, Share, Export

In the bar above the report. Export opens every format in one panel, the .repx first; Share needs an account.

The conversation

The conversation panel

Down the left of the report: every request of the project in one thread, with the message box at its foot. Each message stays pinned at the top while you read Forma's replies to it, and carries its time, Copy, Edit and Withdraw, and its versions when you edited it (1/2, with arrows between them). Forma's reply carries Copy, Good reply and Bad reply, Try again, and for a change what was Changed, with Undo and Redo; the eye on a message shows what it changed on the Preview.

+, Tools and the house style

In the box: + uploads files; Tools (the / button, or / typed in an empty box) puts a request in the box to finish: a total, a group, a column, the paper or the headings; the palette turns your house style on or off. The examples are on the empty workspace's home.

Mark an area

On the Preview, the rail at the right holds Select and Mark an area. Mark (or M) lets you drag a box over the report: every control in it is selected and goes to the box as one chip, to ask the chat about or to change with the toolbar. V goes back to selecting one at a time.

Search, download and fold

The panel's search marks every match and Enter goes to the next; its download saves the whole chat as a Markdown file. Collapse, at the panel's top right, folds the panel and the box to one square at the top left, with Forma's mark in it; Expand opens it again, to see the whole report.

The command menu

Ctrl+K, then type: a view, an export, Share, test data, a zoom, Go to a control, a project or a panel. "?" lists every keyboard shortcut.

Data and binding

A report designed from a picture prints the values it saw. The Data view binds them to your fields, so it prints your records instead. Attach a data file to a message (CSV, TSV, JSON, text, SQL, Excel or Word) and its fields are used from the start; or bind an existing report in three steps.

1 · Your data

Paste a JSON row, a CSV, a CREATE TABLE statement or a list of field names. It is read in your browser, never sent anywhere.

2 · Map the columns

Each column of the report, the sample it shows now, and the field it should print.

2b · Prompt-to-Expression

For a column that is worked out rather than read, describe it — "quantity times unit price, less the discount" — and Generate writes the DevExpress expression; Use expression puts it on the column. It may name only fields your data has, and waits while a problem is listed.

3 · Write the bindings

Apply to the .repx writes them into the file. The view then says how many fields the report is bound to, or, for a report that cannot be bound yet, why.

Your SQL Server data

Forma in your browser never connects to your server. It reads your database’s layout from a script you run yourself, writes the report’s data source the way DevExpress does, and leaves the connection to your application, which already has it. The steps are on the Data view.

1 · The layout script

Copy the layout script and run it in SSMS on your database. It reads SQL Server’s catalog only: no rows, no logins, nothing changed. Click its one result cell, copy all of it, and paste it on the Data view or drop the file into the chat. Up to 5 databases are kept in this browser.

2 · Sample rows, if you like

A second read-only script takes 5 rows from each table the report reads, so columns can be matched by the values they print and the Preview can show real rows. Forma keeps at most 10 rows a table and 200 characters a value.

3 · What the report reads

A table or view with the joins its foreign keys suggest, a stored procedure, or custom SQL: one SELECT, checked against the layout, so a table or column your database does not have is refused. A table pointing back, such as an order’s lines, prints as a detail band under each record.

4 · Into the report

Write into the report writes DevExpress’s own SQL data source, its parameters (several values, a list of values, one list depending on another) and calculated fields. The connection is a name, as your application’s config knows it, never a connection string or a password.

5 · In your application

The Spec shows the connectionStrings entry the name needs and the code that runs the report.

<connectionStrings>
  <add name="Sales" providerName="System.Data.SqlClient"
       connectionString="Data Source=YOUR_SERVER;Initial Catalog=Sales;Integrated Security=True" />
</connectionStrings>

var report = XtraReport.FromFile("report.repx", true);
report.ExportToPdf("report.pdf");

Supported controls

Regions of your design are mapped to real DevExpress controls. These are the ones Forma asks for by name; where the mockup and the file differ, it is said so below.

XRLabel

Headings, field labels, addresses and values. Carries font family, size and weight, bold and italic, horizontal and vertical alignment, wrapping, colour, and per-side borders.

XRTable

Line-item grids, as a real table with populated rows and cells weighted relatively — not a grid faked out of loose labels that falls apart when a column moves.

XRPictureBox

Logos, stamps and photo slots. Each picture is located in your upload and cropped out of it, so the mockup shows your own artwork. In the file it is placed and sized where the picture was, for you to point at the image in the designer: the image itself is not written into the .repx.

XRLine

Rules and dividers, placed at exact coordinates.

XRPageInfo

Page numbers and dates, where the source has them or when you ask for them in the chat.

XRCheckBox

A tick box, checked or not, or bound to a yes-or-no field.

XRPanel

A box that holds other controls and moves them as one. The mockup draws what is inside it.

XRShape and cross-band lines

Rectangles, ellipses and lines, and the lines and boxes drawn from one band to another, as on a form with a border round the page. The Preview draws them; the mockup does not.

XRCrossTab

A pivot of rows against columns, written with the layout DevExpress generates for it. The Preview draws its grid over test data; the mockup marks where it sits.

XRSubreport and a table of contents

Kept from a report you bring; Forma does not invent a subreport. A table of contents is built from the report's bookmarks.

XRBarCode

Written into the file as a real barcode control, carrying its symbology. In the mockup it is a decorative stand-in: positioned and sized, but its content is not drawn.

Charts

A real XRChart in the file, with a series bound to the fields the axes name — bar, column, line, area, scatter and pie. In the mockup it is drawn stylised from its type and values. That is not a charting library and should not be read as data; the file carries the control, the picture is an approximation of it.

Gauges and sparklines

A dial or a trend line becomes a real XRGauge or XRSparkline, carrying its value, range and target. On screen it stays a positioned placeholder — the mockup draws no needle.

The .repx file

The file is standard XtraReportsLayoutSerializer XML. Everything is positioned in the report's unit, by default hundredths of an inch — 100 units to the inch, which is the unit DevExpress itself stores — so a Letter page is 850 × 1100.

<?xml version="1.0" encoding="utf-8"?>
<XtraReportsLayoutSerializer SerializerVersion="23.2.3.0"
  ControlType="DevExpress.XtraReports.UI.XtraReport"
  ReportUnit="HundredthsOfAnInch"
  PageWidth="850" PageHeight="1100">
  <Bands>
    <Item1 ControlType="TopMarginBand" HeightF="100" />
    <Item2 ControlType="DetailBand" HeightF="640">
      <Controls>
        <Item1 ControlType="XRLabel" Text="INVOICE"
          LocationFloat="40,45" SizeF="400,30" />
      </Controls>
    </Item2>
  </Bands>
</XtraReportsLayoutSerializer>

Before you can download it, Forma parses the XML and checks that it has the right root element and a <Bands> section. A malformed generation therefore surfaces in the browser rather than when the designer refuses the file. It is also audited for what DevExpress would drop or print wrong. A generation that ends without a complete file is repaired where it can be, and otherwise marked as failed with Try again, never handed to you as a broken file.

What the checks find

The audit runs after Forma's own repairs, so what it lists is what is still wrong. It blocks nothing. An error means DevExpress will lose content or refuse part of the file; a warning means it will print differently from how it looks. The REPX view lists them under a count, and a reply after a change says how many the checks found.

Errors

A file that stops before its end; a reused Ref, which makes the designer drop content without a word; a total with no running scope, which prints blank; a detail report with no Detail band; a calculated field with no expression or a duplicate name; a cross-tab with no layout; a formatting rule that points at nothing.

Layout

Controls that overlap, leave the page or fall below their band; a band taller than the page; a grid drawn as loose labels rather than a table; a page size that does not match the paper.

Data

A parameter used but not declared, or declared and unused; a group with no fields; a sort on the wrong band; a chart with no series; a subreport with no source.

Accessibility

Text too small, contrast too low, a picture with no description: the three checks DevExpress's own designer runs on every edit.

Settings and what is worked out

Nothing has to be set before a run. What used to be a configuration dialog is worked out from what you bring, and anything else is a sentence in the chat. Settings shows what was worked out for the last request, and why.

DevExpress version

The version a .repx you bring declares, otherwise the version of the last one you brought, otherwise 23.2. The tag is not a gate: a report targeting a newer release still opens, and the designer rewrites the version when it saves.

Paper

Letter, A4, Legal or Tabloid, portrait or landscape: from the page you attach, then your words ("on A4, landscape"), then your region — Letter in the Americas and the Philippines, A4 elsewhere.

Report unit

Hundredths of an inch, tenths of a millimetre, or pixels, read from a .repx you bring or the last one. This is the scale every coordinate and size in the generated file is written in — change it and LocationFloat and SizeF mean something different, so it has to match what your report expects. Hundredths of an inch is the DevExpress default and what a Letter page of 850 × 1100 refers to. The REPX pane names the scale in use, so the file you are about to export is never ambiguous. Font sizes are the one exception: they are always in points, whatever this is set to.

Direction

Right to left when the text you bring reads that way.

Data

The fields from a data file you attach, or the Data tab, or the columns your words name; a stored procedure from your words or your data.

The model: found for you, and yours to change

Google retires models "for new users", so a hard-coded model id is a time bomb — an existing project keeps working while every freshly created key gets a 404. So Forma probes which models your key can actually reach, once per session, and uses the best one that answers (Auto). The box offers Fast and Balanced beside it, and Settings → AI swaps Gemini for a local AI (Ollama or LM Studio) or OpenRouter's free models.

Saving your work

Saved as you work

There is nothing to remember to do: a project is saved a moment after each change, and as soon as a message is sent. Save above the report saves at once.

Signed in

Projects are saved to your account and appear on every device you sign in from.

Signed out

Projects stay in this browser. Reload the page and they are still there — they simply do not follow you to another machine.

Either way

Your API key is never part of what gets saved.

Your uploads travel inside the saved conversation, so a very large design can outgrow a single cloud record. When that happens Forma re-saves the project without the source thumbnails and tells you it did — keeping the specification, the layout and the XML is strictly better than losing the save. A saved project without its thumbnails still reopens and still exports.

Sharing a report

Share a report as you would a document: sign in, open it and choose Share above the report. What you share is a copy of the report; the conversation is never part of it.

Restricted

Only the people you add by email address, up to fifty, can open it, signed in with that address verified.

Anyone with the link

Opens for anyone who has the link, without signing in.

Sending it

Forma sends no email. Copy link, and send it yourself however you like.

What they see

The report's name, its Preview, read-only, and Download .repx. A link that is not theirs to open says so, and nothing else.

Keeping it current

The copy stays as it was shared until you choose Update the shared copy.

Stopping

Stop sharing, and the link stops opening. Deleting the project, or your account, deletes its shared copies too.

Memory and house style

Forma can keep what you tell it and learn how your reports usually look. Both stay in this browser.

Remember

Start a message with remember or from now on — "From now on, put the logo top right" — and Forma keeps it for the reports after. A question is never kept, and nothing else you say becomes a memory.

Seeing them

Settings → Memory lists every memory, with a switch to pause it, Edit and Forget; Remember adds one by hand.

Learning your style

With Learn the style of reports I keep on, a report you export or save counts as kept, and from two of them Forma learns your house style. The newest thirty are kept; Forget kept reports and Forget everything ask before they act.

The report library

Report library in the sidebar holds reports you have already published, so Forma can match their formatting. Add .repx files, several at once; before anything is stored, every text, name, field, data source, expression and link in them is replaced, keeping only positions, fonts, colours and formats. A report is used only once you tick it as house style — nothing is used until you do. The library lives in this browser, and adding to it uses your Gemini key.

Batch generation

The Batch panel turns a set of legacy reports into a set of .repx files — each source document becoming its own report. That is the opposite of attaching several files to the composer, where several pages build one report, and the two are indistinguishable from the files themselves, so the distinction is made by where you put them.

One at a time, or two or three

Files run one at a time by default. Your key carries the quota, and forty simultaneous requests turn a slow success into a fast 429; a key whose quota allows it can run two or three at once.

A verdict per row

Each finished row carries the structural audit's answer in the same words the REPX pane uses — clean, N warnings, or N errors and content will be lost — because the point of running forty files is knowing which of the forty are worth opening.

Stop and retry

Stop cancels what has not started and leaves the request already in flight alone, since it is billed to your key either way. Retry requeues the failed and cancelled files and keeps what succeeded. A quota, key or permission failure stops the whole run rather than producing forty identical errors.

Taking them away

A finished row opens in the workspace or downloads on its own, and Download as .zip takes them all at once.

Revision history

Every generation, refinement and data-binding pass is kept in the Revisions panel, newest first, with what it changed — so a refinement that made the report worse is one click from being undone.

What changed, not just when

The difference is worked out structurally, by control name: added, removed, moved, resized, retyped, plus any change in the band count. A line-by-line comparison of two XML files would be almost entirely noise, because the model rewrites whitespace and attribute order freely between runs.

Restoring is itself recorded

Going back to an earlier version does not lose the newer one. Otherwise Restore would be the very trap the panel exists to remove.

Nudging is not a revision

Dragging or retyping a control on the Preview is undone with Undo at the corner of the report, or Ctrl+Z, one step per gesture. Recording those here would bury the three or four versions you actually want under forty small adjustments.

How long they last

Signed in, the newest ten are saved with the project and come back when you reopen it. Signed out, they live for the session. The panel says which of the two you are getting.

Keyboard shortcuts

The same list the workspace shows when you press ? outside a text field. On a Mac, ⌘ takes the place of Ctrl.

Troubleshooting

Cannot sign in

With Google, the sign-in opens in a pop-up: if nothing appears, allow pop-ups for this site and try again. With an email address, check it is the one the account was made with; Forgot password on the sign-in page sends a reset link. Signing in is optional — Forma works signed out, with your work kept in this browser — and Your account has the rest.

"No longer available"

A model your key could once reach has been retired. Forma clears its cached choice, re-detects and retries once, by itself. If it persists, the key has access to no supported model.

Quota exceeded

Your key has no remaining allowance on that model. Forma sets the model aside for as long as Google says the limit lasts, so the next request starts on another model your key can reach. The allowance is between you and Google — Forma has no quota to share, since it uses no key of its own.

Is it down?

Forma's live site is checked every three hours, and the latest check says whether it passed. An outage of the AI or of sign-in is often Google's: see the Gemini API status and the Firebase status.

Model overloaded

Google's capacity for that model is momentarily exhausted. Forma retries it with a growing pause, then moves to another model your key can reach. Editing the prompt does not help; waiting does.

"Forma built this draft without it"

The AI could not answer, and the reply says why: offline, out of quota, overloaded, not reachable, or a context window too small. A draft Forma built itself, from the text OCR read and its own models, stands in so you are not left with nothing; send the request again when the AI is back to have it designed in full.

A local AI does not answer

Check that Ollama or LM Studio is running at the server address in Settings → AI, and that the model named there is loaded. "Too small" means the context window: start it with 32,768, as Choosing your AI says. A model that spends its whole answer reasoning writes no report; choose another.

Nothing happens on send

Check that a key is set. With none, the box is locked and its button opens Settings at the key.

The layout is roughly right

Upload the original PDF rather than a screenshot of it. Exact strings and coordinates come from the text layer, which a screenshot does not have.

Generation feels slow

The first request of a session also pays for model detection, and a picture's words are read by OCR before it is sent. Stop aborts the request for real.

Frequently asked questions