You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`edge-agents` is the open-source core of the [ForestHub](https://foresthub.ai)
12
-
platform. It contains the Go runtime engine, a multi-provider LLM proxy with
13
-
first-class support for on-device small language models, the OpenAPI contracts
14
-
that define every wire format, and the React-based visual workflow builder.
15
-
The hosted multi-tenant control plane is a separate commercial product and is
16
-
not in this repository.
11
+
Offline by default. GPIO, MQTT, OPC-UA as first-class nodes. Local SLMs alongside cloud LLMs in the same workflow.
17
12
18
-
> Status: `go/v1.0.1`. Runtime is in production use; contract and TypeScript
19
-
> APIs may still move. Open an issue before larger changes.
13
+
> Today's AI agents live in datacenters. The interesting workloads — sensors, machines, vehicles, gateways — live everywhere else. **edge-agents** brings the agent paradigm to the devices that interact with the real world: small enough to run on a Pi 5, capable enough to drive an industrial controller, with hardware I/O as native primitives instead of REST shims.
20
14
21
-
## Features
15
+
## What you can build
22
16
23
-
-**Workflow engine** — graph runtime as a state machine; nodes for LLM
24
-
calls, hardware I/O, MQTT, web search, memory, control flow, and
25
-
expressions.
26
-
-**Cloud LLM proxy** — Anthropic, OpenAI, Google Gemini, Mistral. Provider
27
-
dispatched implicitly from the model id.
28
-
-**Local SLM provider** — typed multi-endpoint registry for on-device small
29
-
language models served by `llama.cpp`, `vLLM`, `Ollama`, or any
30
-
OpenAI-compatible endpoint, with capability-based routing
31
-
(`chat` / `embedding` / `classification` / …).
32
-
-**Visual builder** — React Flow canvas with typed nodes, ports, and live
33
-
validation, embeddable as a component or runnable via the bundled SPA.
34
-
-**Hardware nodes** — GPIO, ADC, DAC, PWM, UART/serial via native Linux
35
-
drivers; digital and analog signal types are first-class in the contract.
36
-
-**Standalone mode** — engine boots and runs workflows with no backend,
37
-
no account, and no outbound calls beyond LLM provider APIs.
38
-
-**Contract-typed wire format** — every API generated from `contract/*.yaml`
39
-
in both Go and TypeScript; CI fails on drift.
40
-
-**Distroless multi-arch container** — `linux/amd64` and `linux/arm64`,
41
-
nonroot, ~15 MB.
42
-
43
-
## Contents
17
+
-**Voice assistant on a Pi with a local SLM** — wake-word → STT → agent → TTS, no internet required
18
+
-**Predictive maintenance on industrial gear** — live OPC-UA vibration stream → LLM decides → MQTT alert
19
+
-**Local RAG on a Jetson** — agent answers grounded in live sensor and machine state, not the public web
44
20
45
-
| Path | What it contains |
46
-
| --- | --- |
47
-
|[`contract/`](contract)| OpenAPI 3.0.3 schemas — single source of truth for Go and TS. |
A workflow is a directed graph of typed nodes — LLM call, hardware I/O, MQTT,
124
-
web search, memory, control flow, expressions — connected by edges with one
125
-
of five types: `control`, `tool`, `agentTask`, `agentChoice`, `agentDelegate`.
126
-
127
-
The engine interprets the graph as a state machine: wait for event → execute
128
-
node → transition. Triggers run as parallel goroutines. The HTTP layer is
129
-
generated by `oapi-codegen` from `contract/engine.yaml` as a strict server;
130
-
the workflow types are generated from `contract/workflow.yaml` and reused
131
-
without modification by the TypeScript model.
132
-
133
-
Engine ports `Lifecycle`, `Retriever`, and `MemoryStore` have offline default
134
-
adapters in `go/engine/local/` (no-op registration, no-op RAG, filesystem-backed
135
-
memory). With the Local LLM provider configured, the engine runs entirely
136
-
without network access.
137
-
138
-
## The contract is the source of truth
139
-
140
-
Schema drift between Go and TypeScript is the highest technical risk in this
141
-
repository. The defense is one authoritative contract with codegen on both
142
-
sides, committed bindings, and a CI job that fails on drift.
74
+
</details>
143
75
144
-
- Edit `contract/*.yaml`.
145
-
-`cd go && go generate ./...` regenerates `go/api/**/*.gen.go`.
146
-
-`cd ts && npm run generate` regenerates `ts/workflow-core/src/api/workflow.ts`.
147
-
- Generated files are committed; CI diffs them against a fresh regeneration.
148
-
149
-
See [`CLAUDE.md`](CLAUDE.md), [`go/CLAUDE.md`](go/CLAUDE.md), and
150
-
[`ts/CLAUDE.md`](ts/CLAUDE.md) for per-language conventions.
151
-
152
-
## LLM providers and on-device SLMs
153
-
154
-
Four cloud providers and one Local provider for on-device inference. Provider
155
-
is dispatched implicitly from the model id; switching from a cloud LLM to a
156
-
local SLM is a one-line model-id change.
76
+
## Features
157
77
158
-
| Provider | Configuration |
159
-
| --- | --- |
160
-
| Anthropic |`ANTHROPIC_API_KEY`|
161
-
| OpenAI |`OPENAI_API_KEY`|
162
-
| Google Gemini |`GEMINI_API_KEY`, or a Vertex AI service account |
163
-
| Mistral |`MISTRAL_API_KEY`|
164
-
| Local | Typed YAML registry (see below) |
78
+
-**Workflow engine** — typed graph runtime; nodes for LLM calls, hardware I/O, MQTT, web search, memory, control flow.
79
+
-**Multi-provider LLMs** — Anthropic, OpenAI, Google Gemini, Mistral, plus a local SLM provider for `llama.cpp` / `vLLM` / `Ollama` / any OpenAI-compatible endpoint.
80
+
-**Visual React Flow builder** — embeddable component or runnable as bundled SPA, with typed parameters and live validation.
81
+
-**Contract-typed wire format** — every API generated from `contract/*.yaml` for both Go and TypeScript; CI fails on schema drift.
165
82
166
-
###Local provider
83
+
## Local SLM provider
167
84
168
-
The Local provider models the common edge-SLM topology directly: one process
169
-
per model — the standard for `llama.cpp` / `llama-server` and `vLLM` — each
170
-
declaring its capabilities and, for embedders, its output dimension. The
171
-
proxy routes requests to the right model by capability, so a workflow can use
172
-
a chat SLM, an embedder, and a classifier in one pass without knowing where
173
-
each one is hosted.
85
+
One process per model — the standard for `llama.cpp` and `vLLM` — each declaring its capabilities. The proxy routes requests by capability, so a workflow can use a chat SLM, an embedder, and a classifier in one pass without knowing where each one is hosted.
| Bare-metal MCU (Cortex-M) | Not supported by the Go engine. Contract is portable; dedicated MCU runtime is on the roadmap. |
218
129
219
-
## Releases
130
+
## Architecture
131
+
132
+
A workflow is a directed graph of typed nodes — LLM call, hardware I/O, MQTT, memory, control flow, expressions — connected by edges with one of five types: `control`, `tool`, `agentTask`, `agentChoice`, `agentDelegate`. The engine interprets the graph as a state machine: wait for event → execute node → transition. The contract (`contract/*.yaml`) is the single source of truth — Go and TypeScript both regenerate from it, CI fails on drift.
220
133
221
-
- **Go runtime** — tagged `go/vX.Y.Z`. Consumers pin with
222
-
`go get github.com/ForestHubAI/edge-agents/go@vX.Y.Z`. Current: `go/v1.0.1`.
223
-
- **TypeScript packages** — `@foresthubai/workflow-core` and
224
-
`@foresthubai/workflow-builder`ship in lockstep at the same version.
See [CONTRIBUTING](.github/CONTRIBUTING.md) and the
243
-
[Code of Conduct](.github/CODE_OF_CONDUCT.md). Open an issue before any
244
-
non-trivial change. Every contribution is accepted under a Contributor
245
-
License Agreement that preserves the dual-licensing model.
158
+
See [CONTRIBUTING](.github/CONTRIBUTING.md) and the [Code of Conduct](.github/CODE_OF_CONDUCT.md). Open an issue before any non-trivial change. Every contribution is accepted under a Contributor License Agreement that preserves the dual-licensing model.
246
159
247
160
## Security
248
161
249
-
Do not open public issues for security vulnerabilities. Use
or email **root@foresthub.ai**. See [SECURITY.md](.github/SECURITY.md) for
252
-
scope and process.
162
+
Do not open public issues for security vulnerabilities. Use [GitHub private vulnerability reporting](https://github.com/ForestHubAI/edge-agents/security/advisories/new) or email **root@foresthub.ai**. See [SECURITY.md](.github/SECURITY.md) for scope and process.
253
163
254
164
## License
255
165
256
-
`edge-agents`uses a **two-tier license model** designed to make the wire
257
-
format and the headless workflow model maximally reusable while keeping
258
-
the engine and the visual builder protected under copyleft.
166
+
`edge-agents`uses a **two-tier license model** designed to make the wire format and the headless workflow model maximally reusable while keeping the engine and the visual builder protected under copyleft.
259
167
260
168
| Component | License | Why |
261
169
| --- | --- | --- |
@@ -265,12 +173,9 @@ the engine and the visual builder protected under copyleft.
265
173
| [`ts/workflow-builder`](ts/workflow-builder) (React canvas) | **AGPL-3.0-only** or **commercial** | Same dual-license terms as the engine. |
266
174
| [`ts/app`](ts/app) (reference SPA, not published) | **AGPL-3.0-only** | Reference implementation, not for redistribution. |
267
175
268
-
For the AGPL components, the AGPL network clause applies — providing a
269
-
modified version over a network requires making the corresponding source
270
-
available to users of that service.
176
+
For the AGPL components, the AGPL network clause applies — providing a modified version over a network requires making the corresponding source available to users of that service.
271
177
272
-
Third-party components retain their own licenses; see
273
-
[THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) and [NOTICE](NOTICE).
178
+
Third-party components retain their own licenses; see [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) and [NOTICE](NOTICE).
0 commit comments