anfra

module
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: Apache-2.0

README

anfra

Open-source framework for building trusted custom BI apps

Website · Docs · Live demos · Quickstart

Funnel analysis app built with anfra

A funnel analysis app built by a coding agent with anfra. Try it live →

What is anfra?

anfra is an open-source framework for building trusted custom BI apps with AI coding agents.

  • Traditional BI tools make the numbers easy to trust, but often limit teams to fixed dashboard layouts and interactions.
  • Coding agents can build custom dashboard apps in HTML and JavaScript, but wiring each view to the warehouse and handling interactions is easy to get wrong and hard to reuse.

With anfra, your coding agent builds the app with HTML, JavaScript and any charting library. The anfra SDK connects that app to a governed semantic foundation with consistent, reusable metrics and business context.

anfra also provides analytics interactions (filtering, drill-downs, and period comparisons) out of the box, along with built-in provenance and lineage to help users understand where their data comes from and how metrics are calculated.

You get the custom layouts of a coding agent and the trusted numbers of a BI tool.

Key features

  • Custom layouts: your coding agent writes plain HTML and JavaScript with any charting library, so apps aren't limited to the chart types, filters and layouts a BI tool offers.
  • Governed semantic foundation: models, datasets and metrics live as code in your repo, and your data team reviews changes like any other code. Every app uses the same definitions.
  • Interactions built in: the SDK handles cross-filters, drill-downs and period comparisons, so the agent doesn't write that SQL by hand.
  • Built-in provenance and lineage: open Inspect on any number to see the query that produced it and the metric definitions behind it.
  • Built for coding agents: agent skills teach Claude Code, Codex and Cursor to write anfra models and apps, and an MCP server lets the agent read your models and metrics.

These are custom BI apps (HTML/JS/CSS) generated by coding agents on top of the anfra SDK and server.

Cohort heatmap
Cohort heatmap
Revenue, orders, or units by signup cohort and months since signup. Click a cell to filter, or right-click to see the underlying rows.

BigQuery cost & usage
Daily cost by team, tool, project, and query, with a month-end forecast against budget. Click a bar to filter.
MRR reconciliation
MRR reconciliation
Merge correction events so upgraded and downgraded MRR aren't overstated. Preview the effect before submitting.
Metric sheet
Metric sheet
A statement-style table with one column per period. Add metrics, breakdowns, sections, and % change rows.

View more demos →

Quickstart

Fastest start: one prompt

Open an empty folder in Claude Code, Codex or Cursor and paste:

Set up anfra (https://github.com/holistics/anfra) in this folder and build this app on my data: [describe the app, for example "a weekly revenue dashboard by product and region", or leave this and I'll pick from your suggestions].

1. Install the CLI with `curl -fsSL https://anfra.ai/install.sh | bash`. It goes to `~/.anfra/bin/anfra`; use that full path if `anfra` isn't found. Then run `anfra skills install`. If the anfra skills aren't available to you in this session yet, read them from https://github.com/holistics/anfra-skills instead.
2. Run `anfra init` here. Ask me which database to connect, then fill in `.anfra/data_sources.yml` with placeholders for passwords and keys. Let me enter those myself, and don't print them.
3. If I didn't describe an app above, look at the tables, suggest two or three apps I could build, and wait for me to pick one.
4. Model only the tables and metrics that app needs in `models/` and `datasets/`, and run `anfra validate` until it passes.
5. Build the app in `apps/`.
6. Run `anfra serve` and give me the link to the app.

Replace the text in brackets with the app you want, or leave it and the agent will suggest some once it can see your tables. It stops to ask which database to connect and lets you enter the credentials yourself. Use a read-only database user.

Or step by step

1. Install anfra
curl -fsSL https://anfra.ai/install.sh | bash

The installer puts anfra in ~/.anfra/bin and adds it to your PATH. Works on macOS and Linux; see Installation for other options.

Open a new terminal, then install the skills that teach your coding agent to build with anfra:

anfra skills install

This installs them into Claude Code and Codex; add --agent cursor for Cursor. For other agents, run npx skills add holistics/anfra-skills.

2. Create a project and connect a warehouse
anfra init my-project
cd my-project

This creates the models/, datasets/, and apps/ folders and a .anfra/data_sources.yml config file, which is added to .gitignore so your credentials stay out of Git.

Replace the placeholders in .anfra/data_sources.yml with your warehouse credentials. See Data sources for Snowflake, BigQuery, ClickHouse and the others.

3. Ask your agent for an app

Open the project in your coding agent and ask for an app:

Use the build-data-app skill. Look at my orders data and build a revenue overview: monthly trend and revenue by region. Clicking a region should filter the trend.

With no models yet, the agent defines the datasets and metrics it needs as code in models/ and datasets/, then builds the app in apps/.

4. Run the server
anfra serve

Open http://127.0.0.1:7878/ to see your apps. An app saved as apps/revenue.html opens at /apps/revenue and reloads as you or the agent edit it.

Run with Docker

To run a project on a server, or without installing anything, use the image. Mount the project at /repo:

docker run -p 7878:7878 -v "$PWD:/repo" ghcr.io/holistics/anfra

The same apps, API and MCP are then at http://localhost:7878/. Other commands run the same way, for example docker run --rm -v "$PWD:/repo" ghcr.io/holistics/anfra validate.

There is one image for every machine: Docker pulls the build for yours (x64 or ARM, Apple silicon included). Tags follow the releases: 0.4.0, 0.4, or latest. The server has no login, so publish its port only to people who may query the project's data.

How anfra works

anfra sits between your app and your semantic layer. It isn't a semantic layer itself: the SDK runs in your page, and the server turns each click into a query on the metrics your semantic layer defines.

  • anfra SDK: a JavaScript library your app uses to request data and wire up filters, drill-downs, and period comparisons. It asks for data by dataset and metric names, not SQL.
  • anfra Server (anfra serve): serves your apps, takes each request from the SDK, turns the interaction (a filter, a drill-down, a comparison) into a query on your semantic layer, runs it on the warehouse, and returns the results. It also serves MCP so coding agents can read your models.

anfra runs on your semantic layer: your models, datasets, and metrics, defined as code. anfra ships with AMQL built in. Support for external semantic layers such as dbt, Cube, Snowflake and Databricks is planned (details).

How anfra works

What it looks like

A revenue page with two charts: revenue by region and a monthly trend. Clicking a region filters the trend.

1. Define a metric once in the semantic layer:

Dataset sales {
  metric revenue {
    label: 'Revenue'
    type: 'number'
    definition: @aql sum(orders.amount) ;;
  }
}

2. Your agent writes the page. It asks for revenue by name and says that a click on one chart filters the other:

const byRegion = app.createQuery('byRegion', {
  dataset: 'sales',
  aql: `explore { dimensions { region: users.region } measures { revenue: revenue } }`,
})
const trend = app.createQuery('trend', {
  dataset: 'sales',
  aql: `explore { dimensions { month: date_trunc(orders.created_at, 'month') } measures { revenue: revenue } }`,
})
app.mapCrossFilter(byRegion, trend)

3. A user clicks "APAC". anfra Server adds the filter to the trend query and runs this SQL (PostgreSQL, with time zone handling trimmed):

SELECT
  DATE_TRUNC('month', "orders"."created_at") AS "month",
  SUM("orders"."amount") AS "revenue"
FROM
  orders "orders"
  LEFT JOIN users "users" ON "orders"."user_id" = "users"."id"
WHERE
  "users"."region" = 'APAC'
GROUP BY
  1

The page never wrote that SQL, and revenue means the same thing in every app that uses it. See the Semantic UI guide for queries, controls, and interaction mappings.

anfra OSS vs anfra Cloud (coming soon)

anfra Cloud is in development and not available yet. It will be our hosted product, built on the same open-source engine, and will add what a team needs to share apps: users and SSO, row-level permissions, hosted apps with sharing links, audit logs and version history.

A project you build with open-source anfra will run unchanged on anfra Cloud. Moving it will take one publish step, with no changes to your models or apps.

  • Use open-source anfra to build and run apps on your own infrastructure, for yourself or a team that doesn't need per-user permissions.
  • anfra Cloud (once available) will let you share apps across your company with logins, permissions and audit logs, without running the server yourself.
anfra (open source) anfra Cloud (coming soon)
Built-in semantic layer (AMQL) ✅ ✅
JS SDK, controls, interactions, inspect ✅ ✅
MCP server + agent skills ✅ ✅
Self-host ✅ Managed
Users, SSO, roles — ✅
Row-level and viewer-level permissions — ✅
Hosted apps: sharing, public links, discovery — ✅
Audit trail, usage monitoring — ✅
Snapshots, versioning — ✅

A paid self-hosted edition with the same features is also planned. Watch this repo to hear when anfra Cloud opens.

FAQ

How is this different from connecting Claude to my warehouse, or a BigQuery, Metabase or dbt MCP?

For a one-off question, not much. The difference shows up when you build apps: metrics defined once instead of re-derived SQL in every app, interactions like drill-down, cross-filter, funnels and period comparisons resolved by the engine, apps that query live data instead of holding pasted numbers, and the query and metric behind each number.

How is this different from Streamlit, Evidence or Hex?

Those give you a framework to write the app in. anfra gives you a semantic backend for any front end the agent writes: plain HTML/JS, no Python runtime, no fixed component set. Metrics and interactions are defined once and shared across every app.

I already have a BI tool. Why would I switch?

anfra is built to replace dashboard BI tools, not to sit beside them. Those tools were designed for building reports by hand in a fixed grid of charts and filters. With a coding agent, your team can build the app they actually need, and anfra keeps it governed: metrics are defined once in the semantic layer, and every number can be inspected back to its query and definition. anfra Cloud, coming later, will add users, permissions and sharing.

Compared with a traditional BI tool, anfra gives you:

  • any layout and interaction your team can describe, instead of a fixed set of chart types;
  • a semantic layer that handles funnels, cohorts, drill-downs and period comparisons as built-in operations;
  • an open-source engine you can self-host for free.

You don't need to switch all at once. Run anfra next to your current tool, rebuild reports in it as you need them, and decide at renewal whether you still need the old subscription.

Why build an app instead of asking the chatbot each time?

Asking a chatbot works for a question you ask once. For questions your team asks every week, an app is built once and then just runs: no tokens spent on each repeat question, and everyone who opens it sees the same numbers computed the same way.

Do I have to learn AMQL?

No. Your coding agent drafts and edits models using the anfra skills, and you review changes like any other code. AMQL compiles to plain SQL you can read.

Can the AI change my metric definitions?

Apps query metrics through the SDK; they don't edit the model. Models are files in your project, so when your coding agent proposes a change to a metric, you review it like any other code change before it takes effect.

Can I use my existing semantic layer?

Not today. anfra ships with AMQL. We plan to support other semantic layers such as Cube, dbt, Snowflake and Databricks, though advanced interactions like funnels and period comparisons will depend on AMQL.

Does my data leave my warehouse? Which AI does anfra use?

Queries run on your warehouse, and the anfra server sends results straight to the page. Apps don't store query results or warehouse credentials by default. anfra doesn't include an AI model: you use your own coding agent, so what the agent can see depends on what you connect it to.

How do I control who can see what?

The open-source server has no login or permissions: anyone who can reach it can open its apps. To restrict access, run it behind your own SSO proxy. Per-viewer permissions (the same app showing different numbers to different users), sharing and audit will come with anfra Cloud when it launches.

Are the numbers computed in the browser?

Numbers come from queries the server runs on your warehouse. Page code can still transform the returned rows in JavaScript; Inspect shows the server query, so anything computed on top of it is visible as page code, not hidden in a metric.

How does anfra relate to Holistics? Will I be locked in?

anfra is built by the team behind Holistics, and AMQL is the semantic layer Holistics runs on. anfra is a separate open-source project, licensed under Apache 2.0, and doesn't need a Holistics account. Your models and apps are plain files in your own repository, and AMQL compiles to SQL you can read.

Learn more

About the team

anfra is built by Holistics, the team behind the Holistics BI platform, dbdiagram.io, and the open-source DBML language.

  • Holistics has been building BI software since 2015. Data teams in 40 countries use it, from early-stage startups to large listed companies. AMQL, the semantic layer built into anfra, is the same one Holistics runs on. The company is self-funded, with 65 people in Singapore and Vietnam.
  • dbdiagram.io and dbdocs.io are database design and documentation tools for developers and data engineers. As of February 2025, 1.4 million users had created 2.5 million DBML documents with them.
  • DBML is our open-source language for defining database schemas, with 3,700+ stars on GitHub and community tools in C#, Go, Java, Python, Ruby and more.

License

anfra is licensed under the Apache License 2.0.

Directories

Path Synopsis
cmd
anfra command
Package engine is the anfra engine's public Go API: with the shared packages hosts build on (shared/apperr, appstep and apptracing, which classify its errors; shared/apikit, httpkit and requestid, the API framework its operations are served by), the only packages outside internal/ that another module may import.
Package engine is the anfra engine's public Go API: with the shared packages hosts build on (shared/apperr, appstep and apptracing, which classify its errors; shared/apikit, httpkit and requestid, the API framework its operations are served by), the only packages outside internal/ that another module may import.
internal
aml
Package aml is the engine's work on the repo's AML as a whole: validating it, and showing its objects.
Package aml is the engine's work on the repo's AML as a whole: validating it, and showing its objects.
app
Package app is the single registry of anfra operations.
Package app is the single registry of anfra operations.
appserve
Package appserve is anfra serve's Data App component, its backend: the pages a browser opens (/apps/<path>, the appserve frontend), the Data Apps under the repo's apps/ (their tree, and the files themselves), who reads them, and live reload.
Package appserve is anfra serve's Data App component, its backend: the pages a browser opens (/apps/<path>, the appserve frontend), the Data Apps under the repo's apps/ (their tree, and the files themselves), who reads them, and live reload.
attribution
Package attribution carries who an invocation is for, so that a log line, a span or an audit record can name them.
Package attribution carries who an invocation is for, so that a log line, a span or an audit record can name them.
cliauth
Package cliauth owns browser OAuth login and durable, machine-local credentials.
Package cliauth owns browser OAuth login and durable, machine-local credentials.
cliui
Package cliui owns inline terminal presentation, not authentication or storage.
Package cliui owns inline terminal presentation, not authentication or storage.
cloudapi
Package cloudapi is the anfra CLI's client of anfra-cloud: the ops `anfra publish` calls, with types written here for them.
Package cloudapi is the anfra CLI's client of anfra-cloud: the ops `anfra publish` calls, with types written here for them.
command
Package command is the framework anfra's commands are written in: a Def declares one, Define checks it, and the Command it makes is what every surface reads: the CLI builds its flags from it, `anfra serve` serves it as the op core.<name>, and the registry (internal/app) describes it.
Package command is the framework anfra's commands are written in: a Def declares one, Define checks it, and the Command it makes is what every surface reads: the CLI builds its flags from it, `anfra serve` serves it as the op core.<name>, and the registry (internal/app) describes it.
command/catalog
Package catalog is the commands over the local search catalog: ingest builds it from the repo's context sources, search queries it, and lineage traces fields through it.
Package catalog is the commands over the local search catalog: ingest builds it from the repo's context sources, search queries it, and lineage traces fields through it.
command/query
Package query is the query commands: query runs a query, query.compile compiles one to SQL, and query.validate checks one.
Package query is the query commands: query runs a query, query.compile compiles one to SQL, and query.validate checks one.
command/show
Package show is the show command: an object of the repo, read from its compiled AML, by the identity the semantic catalog gives it.
Package show is the show command: an object of the repo, read from its compiled AML, by the identity the semantic catalog gives it.
command/status
Package status is the commands that report on anfra itself: version, and status of the warm server and its sidecars.
Package status is the commands that report on anfra itself: version, and status of the warm server and its sidecars.
command/validate
Package validate is the validate command: the repo's AML, checked.
Package validate is the validate command: the repo's AML, checked.
dataperm
Package dataperm carries the data-level permissions one invocation runs under: whether its queries are governed, and the caller attributes that row and column rules are written against.
Package dataperm carries the data-level permissions one invocation runs under: whether its queries are governed, and the caller attributes that row and column rules are written against.
datasource
Package datasource reads a repo's data_sources.yml.
Package datasource reads a repo's data_sources.yml.
envflag
Package envflag reads anfra's on/off environment variables.
Package envflag reads anfra's on/off environment variables.
errcode
Package errcode is the engine's namespace, and the error codes no one domain owns: what Dispatch can fail with whatever a command does.
Package errcode is the engine's namespace, and the error codes no one domain owns: what Dispatch can fail with whatever a command does.
exports
Package exports is anfra's own command.ExportStore: an export's file in the system's temp directory, reached by a link that expires.
Package exports is anfra's own command.ExportStore: an export's file in the system's temp directory, reached by a link that expires.
home
Package home is anfra's own folder on this machine: everything anfra keeps between runs, in one place to find, mount or delete.
Package home is anfra's own folder on this machine: everything anfra keeps between runs, in one place to find, mount or delete.
ingest
Package ingest is the catalog ingestion use-case layer: it builds the request anfra-node needs to ingest context sources into the local search catalog.
Package ingest is the catalog ingestion use-case layer: it builds the request anfra-node needs to ingest context sources into the local search catalog.
logging
Package logging provides the host's structured, aggregated logger.
Package logging provides the host's structured, aggregated logger.
meta
Package meta holds build-time metadata for the anfra binary.
Package meta holds build-time metadata for the anfra binary.
motherduck
Package motherduck is anfra's use of a person's MotherDuck account, to copy a DuckDB file there for an org to query: MotherDuck's own CLI signs them in and uploads, and MotherDuck's REST API makes the org a token of its own (docs/designs/motherduck-copy.md).
Package motherduck is anfra's use of a person's MotherDuck account, to copy a DuckDB file there for an org to query: MotherDuck's own CLI signs them in and uploads, and MotherDuck's REST API makes the org a token of its own (docs/designs/motherduck-copy.md).
publish
Package publish is `anfra publish`: a local repo's files published to its org, as PUBLISH.md (anfra-cloud) describes.
Package publish is `anfra publish`: a local repo's files published to its org, as PUBLISH.md (anfra-cloud) describes.
query
Package query is the query use-case layer: it checks a (dataset, AQL) request, turns it into SQL and runs it, by loading the repo's data sources and driving the sidecars via their clients.
Package query is the query use-case layer: it checks a (dataset, AQL) request, turns it into SQL and runs it, by loading the repo's data sources and driving the sidecars via their clients.
repo
Package repo is a command's AML repo: where its files are read from, and the identity anfra-node keys its compile cache by.
Package repo is a command's AML repo: where its files are read from, and the identity anfra-node keys its compile cache by.
repoconfig
Package repoconfig is a repo's settings file, .anfra/config.yml: committed, written by hand, and by anfra only through SetString, which changes nothing but the value it sets.
Package repoconfig is a repo's settings file, .anfra/config.yml: committed, written by hand, and by anfra only through SetString, which changes nothing but the value it sets.
search
Package search is the catalog search use-case layer: it builds the request anfra-node needs to search the local catalog.
Package search is the catalog search use-case layer: it builds the request anfra-node needs to search the local catalog.
sidecar
Package sidecar is the framework anfra's sidecars are run with: the Config a host gives them, the lifecycle of one it spawns (Process), how its binary is found (Binary), and how a sidecar that does not answer is classified (Unreachable).
Package sidecar is the framework anfra's sidecars are run with: the Config a host gives them, the lifecycle of one it spawns (Process), how its binary is found (Binary), and how a sidecar that does not answer is classified (Unreachable).
sidecar/anfranode
Package anfranode is the anfra-node sidecar, the AML/AQL engine: its supervisor, which spawns one or connects to an external one, and its JSON-RPC client.
Package anfranode is the anfra-node sidecar, the AML/AQL engine: its supervisor, which spawns one or connects to an external one, and its JSON-RPC client.
sidecar/canalquery
Package canalquery is the canal-query sidecar, the SQL execution engine: its supervisor, which spawns one or connects to an external one, and its client.
Package canalquery is the canal-query sidecar, the SQL execution engine: its supervisor, which spawns one or connects to an external one, and its client.
telemetry
Package telemetry installs OpenTelemetry for the anfra CLI and `anfra serve`: the global tracer provider and W3C propagation, which the spans anfra already makes (apptracing's per op, httpkit's per request) go to.
Package telemetry installs OpenTelemetry for the anfra CLI and `anfra serve`: the global tracer provider and W3C propagation, which the spans anfra already makes (apptracing's per op, httpkit's per request) go to.
update
Package update implements anfra's self-update: discover the latest GitHub release, compare it to the compiled-in version, download the binary for this platform, and atomically replace the running executable.
Package update implements anfra's self-update: discover the latest GitHub release, compare it to the compiled-in version, download the binary for this platform, and atomically replace the running executable.
scripts
cloud-url command
cloud-url validates the optional cloud URL before embedding it in a CLI build.
cloud-url validates the optional cloud URL before embedding it in a CLI build.
shared
apikit
Package apikit is the API framework the anfra hosts share: an operation is declared once, as a Def, and served by every host and transport the same way — its input validated against the schema of its type, its errors rendered from their codes, its OpenAPI derived from both.
Package apikit is the API framework the anfra hosts share: an operation is declared once, as a Def, and served by every host and transport the same way — its input validated against the schema of its type, its errors rendered from their codes, its OpenAPI derived from both.
apikit/internal/decode
Package decode is how apikit reads an op's input and checks its output, against the schemas huma generates from the Go types.
Package decode is how apikit reads an op's input and checks its output, against the schemas huma generates from the Go types.
apperr
Package apperr gives errors their meaning: a code a caller can handle, which side is responsible (scope), a default message for quick display, typed details for programmatic handling, and the steps the error passed through.
Package apperr gives errors their meaning: a code a caller can handle, which side is responsible (scope), a default message for quick display, typed details for programmatic handling, and the steps the error passed through.
appstep
Package appstep defines the steps a request goes through: what a step is, and how it describes itself.
Package appstep defines the steps a request goes through: what a step is, and how it describes itself.
apptracing
Package apptracing runs the steps appstep defines.
Package apptracing runs the steps appstep defines.
httpkit
Package httpkit is what every HTTP server built on the anfra packages shares: the request id, the root span, the request log line, panic recovery, and the one renderer of an error, with the HTTP status of each code served.
Package httpkit is what every HTTP server built on the anfra packages shares: the request id, the root span, the request log line, panic recovery, and the one renderer of an error, with the HTTP status of each code served.
jsonkit
Package jsonkit is how anfra reads and writes JSON: encoding/json/v2 with one set of options, used by every package, so a value is encoded the same way whichever door it leaves by.
Package jsonkit is how anfra reads and writes JSON: encoding/json/v2 with one set of options, used by every package, so a value is encoded the same way whichever door it leaves by.
repoformat
Package repoformat is what an anfra repo is, as anything handling one outside the engine needs it: which files make up a repo (Publishable), which of them are Data Apps and what they are called (DataApp, AppLabel), and how a file's content is named (BlobID).
Package repoformat is what an anfra repo is, as anything handling one outside the engine needs it: which files make up a repo (Publishable), which of them are Data Apps and what they are called (DataApp, AppLabel), and how a file's content is named (BlobID).
requestid
Package requestid identifies one request: the id an error body carries, and that leads to the request's log line and its trace.
Package requestid identifies one request: the id an error body carries, and that leads to the request's log line and its trace.
routine
Package routine runs a server's background routines: the work it does beside its requests (docs/designs/background-routines.md).
Package routine runs a server's background routines: the work it does beside its requests (docs/designs/background-routines.md).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL