agni

README

Agni

Agni is an engine for electronic design files. It reads schematics and PCBs from several formats into one neutral, protobuf-defined IR, then checks, diffs, renders, and queries them. The front-end normalizes formats the way a compiler normalizes languages into one AST, so every analysis downstream is written once and works on all of them.

What it does

• Reads many formats into one IR. EDIF netlists and schematics, KiCad schematics and boards, IPC-2581, xschem, and gEDA all parse into the same ir.Design. Adding a reader is one entry in readers/formats/registry.go.
• Structural checks (ERC/DRC-like). Missing I2C pull-ups, unprotected exposed signals, power rails without decoupling, boards that fail track-width rules. Findings come out in plain language and cite the net or component they fire on.
• Revision diff over the IR. Compares two revisions structurally (components, nets, connectivity), not as a text diff of the source files, so it survives reformatting and rename churn.
• Rendering. Faithful schematic and board geometry, or an auto-laid-out netlist graph, to SVG or a WebGL canvas.
• A browser viewer. agni open <design> serves one board and prints its URL; agni serve opens a tree of them. Either renders the design, runs the checks, and locates each finding on the canvas.
• A datalog query surface. Ask arbitrary questions of the design fact base (agni query), the same fact base the rules are built on.
• A datasheet parameter layer. Join a design against extracted datasheet limits and check, for example, that a rail stays inside a part's recommended operating range.

Try it in 60 seconds

No private data needed. The demo/ folder holds two shareable KiCad boards: a clean one and the same board with deliberate design issues.

git clone https://github.com/panyam/agni
cd agni
make agni
./bin/agni check demo/showcase.fires.kicad_pro

findings by rule:
  bulk-cap               2
  decoupling-present     2
  esd-protection         2
  i2c-pull-up            1
  input-protection       1
  test-point-coverage    2

  [error]   i2c-pull-up: SCL (I2C net has no pull-up resistor to a rail)
  [warning] input-protection: VBUS (connector feeds a power input with no fuse or TVS in the path)
  [info]    esd-protection: USB_D+ (externally-exposed signal net has no ESD protection)
  ...

Then open the browser viewer on the same boards:

make demo

Load showcase.fires.kicad_pro in the left tree, press Run checks, and click a finding to locate its net on the schematic. See demo/README.md.

How it works

One contract sits in the middle: the protobuf IR (protos/, generated into gen/). Readers (readers/edif/, readers/kicad/, readers/ipc2581/, and the xschem/gEDA readers) are the only code that knows a file format; they produce ir.Design. Everything else — check/, diff/, render/, the query engine, the web service — consumes the IR and never looks at a source file. Add a reader and every analysis works on the new format for free. Add an analysis and it works on every format for free.

The same shape repeats at two more contracts: a geometry IR that N producers fill and N renderers draw, and a parameter IR that N datasheet extractors fill and the checks read.

Philosophy

• One neutral IR, many formats. A schematic is a schematic whether it came from KiCad, EDIF, or IPC-2581. Normalize each format once, and write every analysis once against the IR. Add a reader and every check, diff, render, and query works on the new format; add an analysis and it works on every format.
• Format-neutrality is enforced, not aspirational. Analyses read the IR, never source files, and the IR carries no field a second format could not populate. Architectural constraints checked in CI keep the core from accreting format-specific special cases.
• Silence is never coverage. A check that cannot evaluate reports "not applicable" or flags what it could not model; it never returns a false pass. Findings cite the net, component, or datasheet page they come from, and unverified data is marked as such. You can always tell "clean" from "not checked".
• Verify against reality. Readers and rules are checked against the native tools (kicad-cli ERC/DRC) and real design exports, not only hand-written fixtures. A feature is done when it works on a real file.
• Open core with a clear boundary. The engine is shareable under Apache-2.0. Proprietary formats, house rules, and confidential designs live in a private extension that depends on the engine without forking it. Company-specific material stays in the extension, never in the shared engine.
• Legible to software engineers. EDA carries decades of domain vocabulary. Agni maps it to concepts software engineers already know (an IR, a linter, a semantic diff, a lockfile), so you can contribute without an EE degree. See the software-analogy map.

Formats read today

Format	Extensions	Netlist	Faithful geometry
EDIF 2.0.0	.edn .edf .edif (netlist), .eds (schematic)	yes	schematic
KiCad	.kicad_sch .kicad_pcb .kicad_pro	yes	schematic + board
IPC-2581	.xml .cvg	yes	board
xschem	.sch (sniffed)	yes	schematic
gEDA gschem	.sch (sniffed)	yes	schematic

Documentation

Full documentation lives at panyam.github.io/agni.

• Getting started — build, symbol libraries for xschem/gEDA, native EDA tools, golden comparisons.
• User guide — concepts, the CLI, checks, diff, and the query language, written for someone new to the tool.
• Software-analogy map — the hardware-to-software analogy map. If you read code but not schematics, start here.
• Overview — the engineering docs: IR and ingestion, geometry and rendering, semantic diff, format primers.
• examples/README.md — runnable walkthroughs, one per feature.
• CONSTRAINTS.md — the enforceable architectural rules. Read before proposing changes.
• Open core — the open-core split: this public engine, and how a private extension adds proprietary readers and rules without forking it.

Status

Agni reads real exports from every listed format and runs its full analysis over them. It is young: the format coverage is bounded (see each reader's notes), the rule catalog is growing, and the datasheet extraction pipeline is early. The architecture is the settled part; the breadth is the work in progress. Issues and readers for new formats are welcome.

Building

Requires Go 1.26 and pnpm (for the web viewer bundle).

cd web && pnpm install && cd ..   # once
make build                        # web bundle + go build ./...
make install                      # install the agni CLI to $GOBIN
make testall                      # the full gate: vet, tests, bundle, web unit tests

License

Apache-2.0. See LICENSE and NOTICE.

Documentation

Overview

Package agni composes the engine. It is the entry point for a program that embeds Agni as a library rather than running the `agni` binary: one call produces the composed rule catalog, the composed relation registry, and the services that run over them.

It exists because composing correctly means getting FOUR independent global registration seams right, and three of them fail quietly when a binary misses one. A program that forgets stdlib/rules/builtin has an empty catalog, one that forgets stdlib/relations has an empty fact base, and either reports every design clean. New refuses both rather than running, so the composition mistake surfaces at startup instead of as a green report on a design nobody checked.

Files are NOT this package's business. Every option takes a VALUE (a loaded profile set, a parsed declaration, an fs.FS), never a path, because configuration travels as a value and reading it is the caller's world (C22, C13). The CLI reads its flags and hands the results here; an embedder reads its own config however it likes and does the same.

Index

• Variables
• type Engine
  • func New(opts ...Option) (*Engine, error)
  • func (e *Engine) Catalog() *check.Catalog
  • func (e *Engine) ProfileIndex() map[string][]profiles.Profile
  • func (e *Engine) ProjectResolver() *service.ProjectResolver
  • func (e *Engine) ProjectService() *service.ProjectService
  • func (e *Engine) Registry() *facts.Registry
  • func (e *Engine) RuleServices(d RuleServiceDeps) (*service.CheckService, *service.ReviewService)
  • func (e *Engine) Warnings() []string
• type Option
  • func WithConfigResolver(c service.ConfigResolver) Option
  • func WithFSProjectStore(trees ...Tree) Option
  • func WithIntent(d intent.Declaration) Option
  • func WithProducerVersion(v string) Option
  • func WithProfiles(ps []profiles.Profile) Option
  • func WithProjectResolver(r *service.ProjectResolver) Option
  • func WithProjectStore(s service.ProjectStore) Option
  • func WithRelations(opts ...facts.Option) Option
  • func WithSources(srcs ...check.RuleSource) Option
  • func WithoutDatalogRules() Option
• type RuleLoader
• type RuleServiceDeps
• type Tree

Variables

var MissingBuiltinsError = errors.New(
	`agni: the built-in rule catalog is not installed, so none of the shipped EE rules will run and a ` +
		`design is checked only against whatever this program composed itself. ` +
		`Add: import _ "github.com/panyam/agni/stdlib/rules/builtin"`)

MissingBuiltinsError reports that the built-in rule source was never installed, so the shipped EE rule catalog is absent and a run reports only whatever the caller composed itself.

It asks check.BuiltinRules rather than measuring the composed catalog, which would not catch this: stdlib/profiles registers its own source from an init and this package imports it, so a program missing the built-ins still composes a NON-EMPTY catalog holding the interface-profile rules alone. A size check would pass while every rule the engine is known for was missing.

var MissingRelationsError = errors.New(
	`agni: no fact relations are installed, so every datalog rule matches nothing and reports clean. ` +
		`Add: import _ "github.com/panyam/agni/stdlib/relations"`)

MissingRelationsError reports that no relation catalog was installed, so the fact base is empty and every datalog-authored rule matches nothing. This is the failure examples/extension carried a hand-written warning comment about, since it neither fails to build nor errors at runtime.

Types

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is a composed engine: one rule catalog, one relation registry, and the project-resolution ports the services run against. It is built once by New and never mutated, so two surfaces built from one Engine cannot disagree about which rules are in effect.

func New

func New(opts ...Option) (*Engine, error)

New composes an Engine from the registered built-ins plus the options given. It fails when a composition seam is unpopulated, because every one of those failures is otherwise a clean report on an unchecked design; see MissingBuiltinsError and MissingRelationsError for the two it can return and what import fixes each.

It returns an error where check.CatalogWith and facts.NewRegistry panic. The divergence is deliberate: those two are called from an init or from a composing main, where a panic at process start is the standard-library convention and the caller is the programmer who made the mistake. New is called by an embedder whose own program has to decide what to do about a bad composition, and a library that panics inside a host's startup path takes that decision away.

func (*Engine) Catalog

func (e *Engine) Catalog() *check.Catalog

Catalog returns the composed rule catalog: the built-ins, every RegisterSource'd suite, and the profile, intent and ad-hoc sources the options supplied. Callers must not mutate the rules it holds.

func (*Engine) ProfileIndex

func (e *Engine) ProfileIndex() map[string][]profiles.Profile

ProfileIndex returns the by-name interface-profile index the review's absence gate reads: an interface counts as evaluating when any profile under its name is in the run, and the item scoped to it unions their nets.

It is exposed because a caller running a review itself needs it, and it MUST come from the same call that built the catalog. An index built separately can disagree with the catalog about which profiles are in effect, and the disagreement is silent: the gate clears on an interface whose rules the catalog dropped, so an item scoped by it scores a clean pass on an interface nothing checked.

func (*Engine) ProjectResolver

func (e *Engine) ProjectResolver() *service.ProjectResolver

ProjectResolver returns the resolver the rule-running services use to find a design's project and compose that project's config into a run. It is nil when no project store was supplied, which the services accept: a design that resolves to no project runs on the engine's composed defaults.

func (*Engine) ProjectService

func (e *Engine) ProjectService() *service.ProjectService

ProjectService returns the project/design listing service, or nil when no store was supplied.

func (*Engine) Registry

func (e *Engine) Registry() *facts.Registry

Registry returns the composed relation registry, for a caller running its own queries through core/query's *From entry points rather than through a service.

func (*Engine) RuleServices

func (e *Engine) RuleServices(d RuleServiceDeps) (*service.CheckService, *service.ReviewService)

RuleServices builds the two services that RUN rules, from this Engine's one catalog: the CheckService behind a check panel and ListRules, and the ReviewService behind the review resources.

They are returned TOGETHER, and the catalog is not a parameter, so a caller cannot hand one surface the composed catalog and the other something else. That drift is what this shape exists to prevent and it is not hypothetical: --profile-path reached both surfaces only after WS3-048, while --intent-path and a naming config's rules reached reviews alone. A rule missing from the check panel's catalog is indistinguishable there from a rule that ran and found nothing, so the disagreement is invisible from the outside.

func (*Engine) Warnings

func (e *Engine) Warnings() []string

Warnings reports compositions that are legitimate but worth saying out loud, each naming the import that would change it. They are warnings rather than errors because an embedder may genuinely want the engine without one of these pieces; an empty catalog or an empty fact base gets an error from New instead. A caller that ignores the slice gets the behaviour it asked for, silently, which is the whole reason the slice exists.

type Option

type Option func(*builder)

Option configures New. Every option carries a VALUE rather than a path, because reading config is the caller's business and configuration travels as a value (C22).

func WithConfigResolver

func WithConfigResolver(c service.ConfigResolver) Option

WithConfigResolver supplies what resolves an analysis config's URIs into engine values: a project's interface profiles, its seeded parameters, its symbol paths, a design's intent. It is the seam where per-design config enters a run, so a server serving several projects gives each one its own composed rules rather than applying one team's config to every design it reads.

func WithFSProjectStore

func WithFSProjectStore(trees ...Tree) Option

WithFSProjectStore supplies the shipped project store, which walks each tree for descriptors. It takes an fs.FS rather than a path so containment is structural: an fs.FS has no parent to climb into, so a resolution walk stops at the tree root.

This is how the default store reaches a caller without the package that implements it becoming public API. Everything true only of storing projects in DIRECTORIES stays behind service.ProjectStore, which is the contract; a caller that outgrows the directory shape implements the port and passes WithProjectStore instead.

func WithIntent

func WithIntent(d intent.Declaration) Option

WithIntent composes a design-intent declaration into the catalog, which is what flips an intent-bound review item from needs-design-intent to a real verdict. Intent is per-DESIGN, so an Engine composed with one is scoped to that design; a server serving many resolves intent per design through the project config instead.

Load it with intent.LoadFile for YAML, or build the Declaration in Go.

func WithProducerVersion

func WithProducerVersion(v string) Option

WithProducerVersion stamps the build identity onto a review's results document, so a stored run records which engine produced it. An embedder passes its own version string; the CLI passes the engine's.

func WithProfiles

func WithProfiles(ps []profiles.Profile) Option

WithProfiles composes interface profiles into the catalog. A profile whose Name matches a built-in SUPERSEDES that built-in's rules rather than running alongside them, and the review's profile index tracks that replacement, so an item scoped to the interface cannot score a clean pass on a profile whose rules are no longer in the run.

Load them with profiles.LoadDir for a directory of YAML, or build the values in Go. Either way the file reading happens in the caller.

func WithProjectResolver

func WithProjectResolver(r *service.ProjectResolver) Option

WithProjectResolver supplies an already-composed resolver, for a caller that built one to share with the services this package does not construct (the design, diff and query services all take the same resolver). It is the composed form of WithProjectStore plus WithConfigResolver and wins over both, so one run cannot resolve projects two ways.

func WithProjectStore

func WithProjectStore(s service.ProjectStore) Option

WithProjectStore supplies the store that answers which projects and designs exist and which design an artifact belongs to. A deployment backed by a PLM system, an index, or a database implements service.ProjectStore and passes it here; WithFSProjectStore is the shipped directory-walking one.

func WithRelations

func WithRelations(opts ...facts.Option) Option

WithRelations composes extra fact relations into the registry, for an overlay that projects its own tuples out of the Model. The built-in relation catalog arrives through the blank import of stdlib/relations rather than through this option, because it installs as one bulk payload.

func WithSources

func WithSources(srcs ...check.RuleSource) Option

WithSources composes arbitrary rule sources into the catalog: a house suite built in Go, a naming convention's rules, anything satisfying check.RuleSource. They compose after the profile and intent sources, and a source implementing check.SupersedingSource replaces what it names.

func WithoutDatalogRules

func WithoutDatalogRules() Option

WithoutDatalogRules declares that shipping with no datalog-authored rule suite is deliberate, and drops the warning New would otherwise record. It changes nothing about the composition. The warning exists because the absence is invisible from a report, and this option is how a caller who meant it says so once instead of filtering the string.

type RuleLoader

type RuleLoader interface {
	service.Loader
	service.ReviewLoader
	service.ConventionLoader
}

RuleLoader is what the two rule-running services need between them. CheckService and ReviewService take different loader interfaces, so naming the intersection lets one call build both without widening either service's own contract.

type RuleServiceDeps

type RuleServiceDeps struct {
	Loader         RuleLoader
	ReviewStore    service.ReviewStore
	Specs          param.ParamProvider
	BaseConvention string
}

RuleServiceDeps is the per-deployment I/O a rule-running service needs and the Engine does not hold: where designs are read from, where stored runs live, the seeded datasheet corpus, and the name of the deployment's base naming convention.

type Tree

type Tree struct {
	Mount string
	FS    fs.FS
}

Tree is one named filesystem WithFSProjectStore searches for project and design descriptors. Mount is the name a mount:// URI addresses the tree by, and FS is its root.