This repository is a conceptual research prototype.
References to "AGI" and "superintelligence" describe aspirational goals and do not indicate the presence of a real
general intelligence. Use at your own risk. Nothing herein constitutes financial advice. MontrealAI and the maintainers
accept no liability for losses incurred from using this software.
This project intentionally avoids reliance on Chainlink VRF or similar third-party subscription services. Randomness and related features are derived locally so the system remains self-contained and auditable.
Continuous Integration
The CI matrix is pinned to the canonical $AGIALPHA token contract (0xa61a3b3a130a9c20768eebf97e21515a6046a1fa, 18 decimals). Each workflow calls python scripts/check_agialpha_config.py to fail fast if the address, decimals, or workflow environment variables drift away from or the Solidity constants. Run the same helper locally before dispatching CI to keep badges green and avoid PR surprises.
The canonical pull-request gate is ✅ PR CI. It runs Ruff plus the focused smoke test suite on pull requests, pushes to main, and merge queue runs.
The full 🚀 Integration CI — Insight Demo workflow is intentionally off the PR path. It runs on pushes to main, release tags (v* / release-*), and manual dispatch for maintainers. Push-to-main runs the full non-release validation matrix (actionlint, Ruff+Mypy matrix, pytest matrix, Insight Browser ESLint, Windows/macOS smoke, MkDocs, Docs Build, Docker build validation, and branch-protection guardrails). Tags/manual dispatch add release-only publish/deploy/signing stages.
🩺 CI Health hard-monitors the canonical required surface (✅ PR CI) and hard-monitors 🚀 Integration CI for merge-surface contexts. workflow_run watchdog executions remain rerun-only (no extra dispatch) because the upstream run already exists; scheduled/manual runs enforce both PR and merge surfaces with missing-run dispatch enabled. Self-monitoring remains opt-in (--include-self), and rerun support helps Repo-Healer progress beyond run-attempt-1 report-only triage. ADMIN_GITHUB_TOKEN enables branch-protection remediation while default tokens stay read-only for admin APIs.
Run CI locally
Create and activate a Python 3.11–3.13 virtual environment, then upgrade pip:
See Quick Deployment for build and deployment details. The 📚 Docs workflow is dispatched manually by the repository owner to publish the updated site to GitHub Pages.
Explore all demos:https://montrealai.github.io/AGI-Alpha-Agent-v0/alpha_factory_v1/demos/ – run ./scripts/open_subdir_gallery.py (or set AF_GALLERY_URL to your own mirror) for a local or online launch. Alternatively execute make subdir-gallery-open to build the gallery if needed and open it automatically.
All browser demos include a mode toggle. Choose Offline to run a Pyodide simulation directly in your browser or switch to OpenAI API when you provide a key. The key is stored only in memory.
Smoke Test Workflow
Trigger the 🔥 Smoke Test job from the GitHub Actions tab to run linting,
unit tests and a short 2‑year simulation in offline mode. The workflow verifies
the ledger output and catches import errors or circular dependencies early.
Important: Run npm run fetch-assets before npm install or executing
./setup.sh to download the browser demo assets. Run this command in a fresh
checkout—or delete existing wasm*/ files first—so placeholder files are
replaced. After the download, verify checksums with
python scripts/fetch_assets.py --verify-only. The helper retrieves the
official Pyodide runtime from the jsDelivr CDN and the GPT‑2 small checkpoint
directly from the Hugging Face CDN. The legacy wasm-gpt2.tar bundle is no longer used.
Override HF_GPT2_BASE_URL
to change the mirror, for example:
The model weights have SHA‑256
7c5d3f4b8b76583b422fcb9189ad6c89d5d97a094541ce8932dce3ecabde1421 for
verification. See
insight_browser_v1/index.md
for additional details.
Ensure Python 3.11–3.13 (<3.14), Node 22.17.1 and mkdocs are installed. The
script mirrors the Docs workflow used for manual
deployment.
Browser Size Workflow
The 📦 Browser Size job ensures the
Insight archive stays under 500 MiB (with a 750 MiB hard cap). Open Actions → 📦 Browser Size and click
Run workflow to start the check. Repository owners can leave run_token
blank. Others must provide the run_token that matches the DISPATCH_TOKEN
secret. The workflow caches pip and npm dependencies using
actions/setup-python and actions/setup-node. Node uses cache-dependency-path to reference
alpha_factory_v1/demos/alpha_agi_insight_v1/insight_browser_v1/package-lock.json,
alpha_factory_v1/core/interface/web_client/package-lock.json,
alpha_factory_v1/core/interface/web_client/staking/package-lock.json and
alpha_factory_v1/demos/alpha_agi_insight_v1/src/interface/web_client/package-lock.json so repeat runs
skip redundant downloads and avoid the “Dependencies lock file is not found”
warning. ci.yml stores these paths in the NODE_LOCKFILES environment
variable so every setup-node step uses the same list. It
applies the same paths for the tests, docs-build and Docker jobs. It
preinstalls numpy, pandas, pytest and PyYAML so the environment check
passes without network hiccups. During the run it also updates the
browserslist cache inside
alpha_factory_v1/demos/alpha_agi_insight_v1/insight_browser_v1andalpha_factory_v1/core/interface/web_client using
update-browserslist-db to ensure the generated assets target the latest
browsers. When running offline or if the update fails, set
BROWSERSLIST_IGNORE_OLD_DATA=true to continue without refreshing the cache.
Update the version in .github/workflows/ci.yml and rerun
npx update-browserslist-db --update-db --yes whenever dependencies change.
CI Workflow
The 🚀 Integration CI workflow verifies the Insight demo with
linting, type checks, unit tests and a Docker build. Open Actions → 🚀 Integration CI — Insight Demo, select the branch or tag to test in the drop‑down and click
Run workflow to dispatch the pipeline. This workflow also runs
automatically on pushes to main and release tags (v*, release-*), while
staying off pull requests. Push-to-main runs now execute the full non-release
validation matrix, while release tags/manual dispatch append publish/deploy tasks. Each job begins
by verifying the actor matches the repository owner only for manual dispatches;
push and tag runs execute automatically for normal integration validation.
Because the first job checks ${{ github.actor }} against ${{ github.repository_owner }},
you must own the repository to run the workflow from manual dispatch.
Jobs following the main test stage include if: always() so the Windows and
macOS smoke tests, documentation build and Docker jobs execute even when the
lint or unit tests fail. This behavior helps confirm that cross‑platform builds
and docs generation succeed while debugging failures.
Dependency hashes are fully locked, including setuptools, so pip install -r requirements.lock succeeds across Python versions. The Windows smoke job now
builds the Insight browser before running tests, ensuring the service worker is
present for the cache version check. Browser assets are cached across jobs using
a deterministic hash derived from the expected checksums, so later stages reuse
the same files. The docs and Docker jobs automatically fetch any missing assets
and open a pull request when checksums drift. See
CI_WORKFLOW.md for a detailed job overview.
All Node.js steps pin the same lockfiles via cache-dependency-path so
actions/setup-node caches npm packages correctly and avoids "Dependencies lock
file is not found" warnings. The paths are:
To publish a release, create a Git tag and run the same workflow on that
tag. The Docker job pushes the agi-insight-demo image to GitHub Container
Registry while the deploy stage attaches the built web client archive to a
GitHub release. If any later step fails the workflow automatically restores
the previous latest tag to avoid shipping a broken image.
Build & Test Workflow
The 🐳 Build & Test job runs linting,
tests and container builds. Open Actions → 🐳 Build & Test and click
Run workflow to start the pipeline. Only the repository owner can run this
workflow. Each job verifies the actor first and exits immediately for
non‑owners, keeping the rest of the jobs from being skipped.
See ADMIN_ACTIONS.md for details on the manual
workflow restrictions and protected environments.
Docker image tags must use all lowercase characters. The workflow's
"Prepare lowercase image name" step sets REPO_OWNER_LC to the lowercased
repository owner so tags like ghcr.io/montrealai are valid.
Launch the integration workflow manually via Actions → 🚀 Integration CI — Insight Demo and click
Run workflow as described in AGENTS.md.
The workflow performs linting, type checks, the full unit test matrix on Python
3.11 and 3.12, Windows and macOS smoke tests, documentation builds, Docker
builds and an optional deploy step for tagged releases.
Verify Docker image signature
The release workflow signs the container using cosign.
Validate the signature before deploying a new version:
Successful verification proves the image came from this repository's CI.
Quickstart
./quickstart.sh
# or using Docker
docker compose up --build
# or one-click image
./run_quickstart.sh
Run npm run fetch-assets before npm install or executing ./setup.sh to
download the Insight demo assets. Delete any old wasm*/ directories or start
from a clean checkout so placeholders are replaced. After fetching, verify the
files with python scripts/fetch_assets.py --verify-only. The helper retrieves
the official Pyodide runtime from the jsDelivr CDN and the GPT‑2 small
checkpoint from Hugging Face.
Override HF_GPT2_BASE_URL or PYODIDE_BASE_URL to use alternate mirrors. See
insight_browser_v1/index.md
for a detailed guide. You can also run python scripts/download_gpt2_small.py
to retrieve the model directly:
As a last resort use python scripts/download_openai_gpt2.py 124M.
Requires Python 3.11–3.13 (<3.14) and Docker Compose ≥2.5.
Alternatively, run the pre-built image directly:
docker run --pull=always -p 8000:8000 ghcr.io/montrealai/alpha-factory:latest
The workflow publishes a separate image for each Python version with tags
py311, py312 and py313. Only the Python 3.13 build also
updates the latest tag so
ghcr.io/montrealai/alpha-factory:latest always refers to the most recent
Python 3.13 image.
Note
The Dockerfiles in this repository pin the base image to Python 3.13.
Keep this in sync with the highest Python version listed in the CI
matrix when updating workflows.
Replace latest with a commit SHA to run that exact build:
docker run --pull=always -p 8000:8000 ghcr.io/montrealai/alpha-factory:<commit>
Set OPENAI_API_KEY and other required secrets in your environment or .env
before launching the container. The orchestrator prints the
project disclaimer when it starts.
Supported OS: Ubuntu 22.04+, Debian 12+, macOS 12+ and Windows 11 via
WSL 2 (recommended for Windows users). Native Windows paths frequently break
volume mounts. Clone this repository inside the WSL file system to avoid these
issues.
wsl --install
wsl --set-default-version 2
wsl --update
# enable "Use the WSL 2 based engine" in Docker Desktop
Clone the repository inside your WSL home directory to avoid path translation errors.
See the documentation for detailed steps and an overview of the project.
For a concise high-level picture of how the main pieces fit together, see docs/ARCHITECTURE.md.
META-AGENTIC α‑AGI 👁️✨
v0.1.0‑alpha
Official and pioneering definition – Meta-Agentic (adj.): Describes an agent whose primary role is to
create, select, evaluate, or re‑configure other agents and the rules governing their interactions, thereby
exercising second‑order agency over a population of first‑order agents. The term was pioneered by
Vincent Boucher, President of MONTREAL.AI.
flowchart TD
Insight["🎖️ α‑AGI Insight 👁️✨"]
Seeds["🌱💫 α-AGI Nova-Seeds 🔐"]
Mark["α-AGI MARK 🔮🌌✨"]
Sovereign["🎖️ α‑AGI Sovereign 👑✨"]
Biz["🌸 α‑AGI Business 👁️✨"]
Market["🪐 Marketplace 👁️✨"]
Jobs["📜 α‑AGI Jobs 👁️✨"]
Agents["👾👾👾🌌👾👾👾 α‑AGI Agents 👁️✨"]
Reservoir["💎 α‑AGI Value Reservoir"]
Architect["🎖️ α‑AGI Architect 🔱✨"]
Council["🔐 α‑AGI Council 👁️✨"]
Nodes["🖥️ α‑AGI Nodes 👁️✨"]
Insight --> Seeds --> Mark --> Sovereign
Sovereign --> Biz --> Market
Market -->|spawn| Jobs --> Agents
Agents -- success --> Reservoir
Jobs -- ΔΣUSD --> Reservoir
Reservoir -. reinvest .-> Seeds
Reservoir -. fund .-> Market
Agents <---> Nodes
Architect <--> Sovereign
Architect <--> Insight
Council --> Sovereign
Humanity’s Structured Rise to Economic Supremacy via Strategic AGI Mastery
🎖️ α‑AGI Insight 👁️✨ — Beyond Human Foresight
Where human foresight reaches its limits, α‑AGI Insight sees beyond. Humanity stands at the precipice of history’s most
profound economic transformation. α‑AGI Insight identifies with pinpoint accuracy those sectors poised for imminent
disruption by Artificial General Intelligence (AGI). With authoritative and rigorously validated projections estimating
economic opportunities surpassing $15 Quadrillion (15 000 trillion USD), today’s strategic anticipation unlocks
extraordinary economic advantages tomorrow.
Precision Forecasting — Identify and proactively engage critical sectors before AGI disruption.
First‑Mover Advantage — Maximize returns through strategic foresight and superior positioning.
A static demo is available via GitHub Pages.
See Quick Deployment for guidance on building the docs and publishing your own copy.
🎖️ α‑AGI Sovereign 👁️✨ — Autonomous Economic Transformation
Meta‑Agentic mastery at global scale. α‑AGI Sovereign represents a revolutionary class of autonomous, blockchain‑based
enterprises deploying advanced Meta‑Agentic frameworks. Through dynamically evolving swarms of intelligent agents, these
enterprises systematically identify and transform global inefficiencies into measurable economic value (“$AGIALPHA”),
fundamentally reshaping market dynamics and strategically realigning global economic structures.
α‑AGI Marketplace 👁️✨ — Decentralized global platform matching strategic AGI tasks with optimal execution.
α‑AGI Jobs 👁️✨ — Autonomous missions precisely targeting identified inefficiencies.
Local:./quickstart.sh | Docker:docker compose up --build
An interactive Colab notebook demonstrates the same zero‑data Insight search loop. Open
colab_alpha_agi_insight_v1.ipynb in
Google Colab to try it online.
Clone the repository at the v0.1.0-alpha tag and run the helper script to start the Insight demo locally:
git clone --branch v0.1.0-alpha https://github.com/MontrealAI/AGI-Alpha-Agent-v0.git
cd AGI-Alpha-Agent-v0
python -c "import alpha_factory_v1; print(alpha_factory_v1.__version__)" # prints 0.1.0-alpha
python check_env.py --auto-install # may run for several minutes
# NumPy and pandas are required for realistic results; omit or add
# `--allow-basic-fallback` to bypass this check.
# Abort with Ctrl+C and rerun with '--timeout 300' to fail fast
./quickstart.sh
Run `pre-commit run --all-files` after the dependencies finish installing.
For the browser-based version, see
insight_browser_v1/index.md.
It requires Node.js ≥22.17. Install the dependencies with
npm ci and build the static assets with npm run build before launching.
The repository includes a .nvmrc file so you can simply run nvm use to
select the correct Node version.
The α‑AGI Insight demo ships with an offline‑friendly command line interface.
After installation, launch the official demo via:
alpha-agi-insight-v1 --episodes 5
# Or run directly from the package
python -m alpha_factory_v1.demos.alpha_agi_insight_v1 --episodes 5
When API keys are configured the program automatically uses the OpenAI Agents
runtime. Otherwise it falls back to the local Meta‑Agentic Tree Search.
The orchestrator also cleans up the OpenAI runtime on exit to release resources.
For production use, invoke the official demo which automatically
checks the environment, selects the best runtime and optionally starts the
Google ADK gateway:
alpha-agi-insight-v1 --episodes 5
This wrapper transparently falls back to the offline Meta‑Agentic Tree
Search when API credentials are absent, ensuring the demo runs anywhere.
For a guaranteed offline run without external dependencies, use:
Setting AGI_INSIGHT_OFFLINE=1 ensures the search loop never attempts network access.
When the host cannot reach the internet the environment checker prints a warning
and the demos continue in offline mode using any cached data. Optional downloads
are skipped automatically.
Several demos ship with small CSV snapshots for offline mode. These samples
mirror data from the demo-assets
repository and cover roughly March–April 2024.
Meta-Agentic Tree Search Demo
An offline-friendly reference implementation focused on recursive agent-to-agent rewrites lives in
meta_agentic_tree_search_v0/README.md.
It demonstrates the best‑first search behind the other examples and runs without external APIs.
<a name="63-offline-mode"></a>
Offline Mode
Follow these steps when working without internet access. See the
documentation for a summary
of required environment variables.
Build a wheelhouse on a machine with connectivity:
./scripts/build_offline_wheels.sh
The script collects all required wheels under wheels/. Copy this
directory to the offline host, for example using scp or a USB drive:
Install from the wheelhouse and verify packages. The setup script
automatically uses a wheels/ directory in the repository root when
WHEELHOUSE is unset:
check_env.py uses the wheels under $WHEELHOUSE. Set
WHEELHOUSE="$WHEELHOUSE" when running pre-commit or the tests so
dependencies install from the local cache. See
Offline Setup for more
details. A short reference lives in the
documentation. If package installation hangs
for more than ten minutes,
check_env.py will time out and suggest using --wheelhouse for
offline installs.
Run the environment check again when the machine is completely
air‑gapped:
Install llama-cpp-python or ctransformers to enable offline inference.
Fetch and build the browser assets (requires Node.js) to run the Insight demo fully offline:
cd alpha_factory_v1/demos/alpha_agi_insight_v1/insight_browser_v1
npm run fetch-assets
npm ci
npm run build
Skipping this step or running without Node.js prevents the service worker
from being generated, so offline functionality is limited.
Bundle Pyodide for offline demos
make gallery-build
This command generates the site/ directory with the Pyodide runtime and demo assets so the browser examples work without a network connection. The service worker caches these files. Use a hard refresh (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd>) or clear site data to pick up new releases.
Skip browser downloads when running the web demo tests offline:
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm test
Enable offline inference by setting AGI_INSIGHT_OFFLINE=1 in
.env or the environment (ensure llama-cpp-python or ctransformers
is installed).
Disable broadcasting to avoid network calls:
export AGI_INSIGHT_BROADCAST=0
Seed the lineage database from existing DGM logs using --import-dgm.
alpha_factory_v1/demos/alpha_agi_insight_v1/docs/sectors.sample.json.
Pass this file with --sectors-file to forecast specific industries.
The built-in Sector-Shock-10 dataset ships with the package and is
located using importlib.resources when running the demo. This allows
simulate to score forecasts even when the repository layout is not
available.
Example (using --sectors-file to customise the simulation):
Empowering Meta‑Agentic visionaries with strategic infrastructure. At the core of α‑AGI Ascension is α‑AGI Architect —
the foundational operational framework for scalable global deployment. Rooted in the groundbreaking “Multi‑Agent AI DAO”
model, α‑AGI Architect delivers immediate, scalable, and adaptive infrastructure ensuring continuous strategic
evolution.
Robust feedback loops driving continuous refinement between Sovereign operations and Architect infrastructure.
Engineered for rapid global scalability and strategic responsiveness.
flowchart TD
%% ─────────────────────────── CORE LAYERS ───────────────────────────
A[🚀 🎖️ α-AGI Ascension 🌌]
B[🎖️ α-AGI Insight 👁️✨]
C[🎖️ α-AGI Sovereign 👁️✨]
D[🎖️ α-AGI Marketplace 👁️✨]
E[🎖️ α-AGI Jobs 👁️✨]
F[🎖️ α-AGI Agents 👁️✨]
G[🎖️ α-AGI Architect 👁️✨]
V[💎 Infinite Value Reservoir]
%% ─────────────────────────── PRIMARY FLOWS ─────────────────────────
A --> B
B --> C
C --> D
D --> E
D --> F
C --> G
G -.↺ Continuous optimisation .-> C
%% ─────────────────────── WEALTH FEEDBACK LOOPS ─────────────────────
E -- Harvest ΔΣUSD --> V
F -- Compound returns --> V
V -- Reinvest capital --> D
%% ────────────────────────────── STYLE ──────────────────────────────
classDef asc fill:#0f172a,color:#ffffff,font-weight:bold,stroke-width:0px
classDef insight fill:#1e3a8a,color:#ffffff,stroke-width:0px
classDef market fill:#0e7490,color:#ffffff,stroke-width:0px
classDef value fill:#fde047,color:#000000,font-weight:bold,stroke-width:0px
class A asc
class B insight
class C,G insight
class D,E,F market
class V value
linkStyle default stroke-width:2px
[ 🎖️ α‑AGI Ascension 🌌 ] launches humanity into an entirely new economic epoch. By systematically harnessing AGI’s
transformative capabilities, it rewrites global economic structures, implicitly realigning international power dynamics
and propelling humanity toward unprecedented sovereign economic prosperity.
Global markets seep USD ✧ trillions/yr in latent opportunity — “alpha” in the broadest sense:
<kbd>pricing dislocations • supply‑chain entropy • novel drug targets • policy loopholes • undiscovered materials</kbd>.
Alpha‑Factory v1 is an antifragile constellation of self‑improving Agentic α‑AGI Agents 👁️✨ orchestrated to spot
live alpha across any industry and transmute it into compounding value.
Definition: An α‑AGI Business 👁️✨ is an on‑chain autonomous enterprise (<name>.alpha.agi.eth) that unleashes a swarm
of self‑improving agentic α‑AGI agents 👁️✨ (<name>.alpha.agent.agi.eth) to hunt down inefficiencies across any domain
and transmute them into $AGIALPHA.
Built atop OpenAI Agents SDK, Google ADK, A2A protocol, and Anthropic’s Model Context Protocol, the
stack runs cloud‑native or air‑gapped, hot‑swapping between frontier LLMs and distilled local models.
TL;DR Quick Start
Check out the v0.1.0-alpha tag for a reproducible environment.
git clone --branch v0.1.0-alpha https://github.com/MontrealAI/AGI-Alpha-Agent-v0.git
cd AGI-Alpha-Agent-v0
python3 -m venv .venv
source .venv/bin/activate
# Install runtime dependencies
# Install runtime dependencies
pip install -r requirements.lock # pinned versions for deterministic setup
# Optional ADK/MCP integration
pip install google-adk mcp
# Requires Python 3.11–3.13 (<3.14)
./quickstart.sh
Run `pre-commit run --all-files` after the dependencies finish installing.
# Open http://localhost:8000/docs in your browser
The adapters initialise automatically when these optional packages are present.
Optional Packages
Install these extras to unlock additional features:
pip install gradio – enables the MuZero planning dashboard.
pip install openai-agents==0.0.17 – activates the official Agents runtime used for commentary.
pip install google-adk and set ALPHA_FACTORY_ENABLE_ADK=true – starts the Google ADK gateway for
cross‑organisation agent exchange.
Install domain‑specific extras as needed (e.g. httpx, feedparser, networkx, lightgbm,
kafka-python, tldextract). Each agent logs a warning when a library is missing and continues in
degraded mode.
Offline installations can omit these lines from the relevant requirements.txt
files if the Agents SDK or ADK gateway are not needed.
To regenerate requirements.lock from requirements.txt with hashes, run:
After running ./codex/setup.sh, which ensures pre-commit==4.2.0
is installed, install the hooks and run a full check:
# Install the exact version if the setup script didn't already
pip install pre-commit==4.2.0
pre-commit install
pre-commit run --all-files # verify hooks after setup
pre-commit run --files <paths> # before each commit
Run pre-commit run --all-files once after the setup script to confirm
everything is formatted correctly. These commands mirror the steps in
AGENTS.md and keep commits consistent.
After editing .github/workflows/ci.yml, run:
pre-commit run --files .github/workflows/ci.yml
python tools/update_actions.py
to validate the workflow with actionlint before committing.
Before opening a pull request, run pre-commit run --all-files to ensure
all hooks succeed.
Run python check_env.py --auto-install before invoking these commands so
optional hook dependencies are installed. When working offline, pass
--wheelhouse <dir> or set WHEELHOUSE to install from a local cache. If
pre-commit isn't found or the version differs, install it with
pip install pre-commit==4.2.0.
When editing the web UI, preserve existing ARIA labels so the interface
remains accessible.
Development Setup
Install the Python dependencies with the helper script:
scripts/setup_env.sh
The script checks for Python 3.11–3.13 (<3.14) and installs requirements.txt and
requirements-dev.txt.
When preparing an offline environment, build a wheelhouse on a machine with
internet access:
./scripts/build_offline_wheels.sh
Copy the resulting wheels/ directory to the target host and set
WHEELHOUSE=$(pwd)/wheels before running check_env.py or the tests so
packages install from the local cache. The repository does not ship these
prebuilt wheels.
%% Legend
%% solid arrows = primary value‑flow
%% dashed arrows = secondary / supporting influence
%% node emojis = domain archetypes
graph TD
%% Core pillars
FIN["💰 Finance"]
BIO["🧬 Biotech"]
MFG["⚙️ Manufacturing"]
POL["📜 Policy / Reg‑Tech"]
ENE["🔋 Energy"]
SUP["📦 Supply‑Chain"]
RET["🛍️ Retail / Demand"]
CYB["🛡️ Cyber‑Security"]
CLM["🌎 Climate"]
DRG["💊 Drug Design"]
SMT["⛓️ Smart Contracts"]
TLT["🧑💼 Talent"]
%% Derived transversal competences
QNT["📊 Quant R&D"]
RES["🔬 Research Ops"]
DSG["🎨 Design"]
OPS["🔧 DevOps"]
%% Primary value‑creation arcs
FIN -->|Price discovery| QNT
FIN -->|Risk stress‑test| CLM
BIO --> DRG
BIO --> RES
MFG --> SUP
ENE --> CLM
RET --> FIN
POL --> CYB
SMT --> FIN
%% Cross‑pollination (secondary, dashed)
FIN -.-> POL
SUP -.-> CLM
CYB -.-> OPS
DRG -.-> POL
QNT -.-> RES
RET -.-> DSG
%% Visual grouping
subgraph Core
FIN
BIO
MFG
POL
ENE
SUP
RET
CYB
CLM
DRG
SMT
TLT
end
classDef core fill:#0d9488,color:#ffffff,stroke-width:0px;
Each agent exports a signed proof‑of‑alpha message to the Kafka bus, enabling cross‑breeding of opportunities.
sequenceDiagram
participant User
participant ORC as Orchestrator
participant FIN as 💰
participant GEN as 🧪
User->>ORC: /alpha/run
ORC->>GEN: new_world()
GEN-->>ORC: env_json
ORC->>FIN: act(env)
FIN-->>ORC: proof(ΔG)
ORC-->>User: artefact + KPI
<a name="4-demo-showcase"></a>
4 · Demo Showcase 🎬
| # | Folder | Emoji | Lightning Pitch | Alpha Contribution | Start Locally |
|---|--------|-------|-----------------|--------------------|---------------|
|1|aiga_meta_evolution|🧬|Agents evolve new agents; genetic tests auto‑score fitness.|Expands strategy space, surfacing fringe alpha.|cd alpha_factory_v1/demos/aiga_meta_evolution && ./run_aiga_demo.sh|
|2|alpha_agi_business_v1|🏦|Auto‑incorporates a digital‑first company end‑to‑end.|Shows AGI turning ideas → registered business.|./alpha_factory_v1/demos/alpha_agi_business_v1/run_business_v1_demo.sh [--pull] [--gpu] (docs: http://localhost:8000/docs)|
|3|alpha_agi_business_2_v1|🏗|Iterates business model with live market data RAG.|Continuous adaptation → durable competitive alpha.|./alpha_factory_v1/demos/alpha_agi_business_2_v1/run_business_2_demo.sh|
|4|alpha_agi_business_3_v1|📊|Financial forecasting & fundraising agent swarm.|Optimises capital stack for ROI alpha.|./alpha_factory_v1/demos/alpha_agi_business_3_v1/run_business_3_demo.sh|
|5|alpha_agi_marketplace_v1|🛒|Peer‑to‑peer agent marketplace simulating price discovery.|Validates micro‑alpha extraction via agent barter.|docker compose -f demos/docker-compose.marketplace.yml up|
|6|alpha_asi_world_model|🌌|Scales MuZero‑style world‑model to an open‑ended grid‑world.|Stress‑tests anticipatory planning for ASI scenarios.|docker compose -f demos/docker-compose.asi_world.yml up|
|7|cross_industry_alpha_factory|🌐|Full pipeline: ingest → plan → act across 4 verticals.|Proof that one orchestrator handles multi‑domain alpha.|./alpha_factory_v1/demos/cross_industry_alpha_factory/deploy_alpha_factory_cross_industry_demo.sh|
|8|era_of_experience|🏛|Lifelong RL stack blending real & synthetic experience streams.|Showcases sensor-motor tools, grounded rewards & non-human reasoning.|cd alpha_factory_v1/demos/era_of_experience && ./run_experience_demo.sh|
|9|finance_alpha|💹|Live momentum + risk‑parity bot on Binance test‑net.|Generates real P&L; stress‑tested against CVaR.|./alpha_factory_v1/demos/finance_alpha/deploy_alpha_factory_demo.sh|
|10|macro_sentinel|🌐|GPT‑RAG news scanner auto‑hedges with CTA futures.|Shields portfolios from macro shocks.|docker compose -f demos/docker-compose.macro.yml up|
|11|muzero_planning|♟|MuZero in 60 s; online world‑model with MCTS.|Distills planning research into a one‑command demo.|./alpha_factory_v1/demos/muzero_planning/run_muzero_demo.sh|
|12|self_healing_repo|🩹|CI fails → agent crafts patch ⇒ PR green again.|Maintains pipeline uptime alpha.|docker compose -f demos/docker-compose.selfheal.yml up|
|13|meta_agentic_tree_search_v0|🌳|Recursive agent rewrites via best‑first search.|Rapidly surfaces AGI-driven trading alpha.|mats-bridge --episodes 3|
|14|alpha_agi_insight_v1|👁️|Zero‑data search ranking AGI‑disrupted sectors.|Forecasts sectors primed for AGI transformation.|alpha-agi-insight-v1 --episodes 5|
Colab? Each folder ships an *.ipynb that mirrors the Docker flow with free GPUs.
The official Docker image bundles PyTorch 2.2.x and Ray 2.10.0. The
notebooks install PyTorch from the PyTorch wheel index
and pin Ray to the same version for compatibility.
Self‑Healing Repo — agents automatically craft patches when CI
fails.
The underlying MetaRefinementAgentonly simulates improvement by
generating placeholder diffs. We hope to replace this with genuine
optimisation based on real performance metrics—contributions are
warmly welcomed.
Note: The alpha_agi_business_3_v1 demo is intentionally left out of the published package. Clone this repository
to run it from source.
flowchart TB
subgraph Macro["Macro‑Finance Δβ"]
FIN[FinanceAgent]:::agent
ENE[EnergyAgent]:::agent
end
subgraph Meso["Supply‑Chain ΔS"]
MFG[ManufacturingAgent]:::agent
LOG[LogisticsAgent]:::agent
end
subgraph Micro["Bio/Chem ΔH"]
BIO[BiotechAgent]:::agent
MAT[MaterialsAgent]:::agent
end
FIN & ENE -->|β feed| ORC
MFG & LOG -->|entropy ΔS| ORC
BIO & MAT -->|latent ΔH| ORC
classDef agent fill:#cffafe,stroke:#0369a1;
Cells with (Δ\mathcal F < 0) glow 🔵 on Grafana; Ω‑Agents race to harvest.
<a name="5-memory--knowledge-fabric"></a>
5 · Memory & Knowledge Fabric 🧠
[Event] --embedding--> PGVector DB
\--edge--> Neo4j (CAUSES, SUPPORTS, RISK_OF)
Agents query mem.search("supply shock beta>0.2")
Planner asks Neo4j: MATCH (a)-[:CAUSES]->(b) WHERE b.delta_alpha > 5e6 RETURN path
SQLite vector store fallback requires numpy
Realistic operation also relies on pandas
<a name="6-5-minute-quick-start"></a>
6 · 5‑Minute Quick‑Start 🚀
This guide assumes the repository is cloned at v0.1.0-alpha. The walkthrough
requires the numpy, yaml and pandas packages which check_env.py installs
automatically when run with --auto-install.
git clone --branch v0.1.0-alpha https://github.com/MontrealAI/AGI-Alpha-Agent-v0.git
cd AGI-Alpha-Agent-v0
./quickstart.sh --preflight # optional environment check
python check_env.py --auto-install # verify & auto-install deps (10 min timeout)
# Install heavy optional packages such as openai_agents, gymnasium and google_adk.
# Running tests without these extras will skip or fail the modules that depend on
# them. Use ALPHA_FACTORY_FULL=1 with check_env.py to ensure they install. See
# `tests/README.md` for detailed instructions.
ALPHA_FACTORY_FULL=1 python check_env.py --auto-install
# Install runtime dependencies
pip install -r requirements.lock
# (If this fails with a network error, create a wheelhouse and rerun
# with --wheelhouse <path> or place the wheels under ./wheels)
# Build a wheelhouse if the machine has no internet access:
# ./scripts/build_offline_wheels.sh
./quickstart.sh # creates venv, installs deps, launches
# Use `--wheelhouse /path/to/wheels` to install offline packages when
# the host has no internet access. The setup script automatically
# sets `WHEELHOUSE` to `./wheels` when that directory exists. When
# working offline, run `python check_env.py --auto-install --wheelhouse
# /path/to/wheels` to verify and install packages. The setup script
# exits with a message if neither network nor a wheelhouse are available.
# Example offline workflow:
# export WHEELHOUSE=$(pwd)/wheels
# python check_env.py --auto-install --wheelhouse "$WHEELHOUSE"
# WHEELHOUSE=$WHEELHOUSE ./quickstart.sh
# WHEELHOUSE=$WHEELHOUSE pytest -q
# Open http://localhost:8000/docs in your browser
# Alternatively, ``python alpha_factory_v1/quickstart.py`` provides the same
# workflow on Windows and other systems without Bash.
# Deploy instantly with Docker (prebuilt image)
docker run --pull=always -p 8000:8000 ghcr.io/montrealai/alpha-factory:latest
# Pull a specific build by commit SHA
docker run --pull=always -p 8000:8000 ghcr.io/montrealai/alpha-factory:<commit>
# The `alpha-factory` CLI also works when the package is installed:
# A short warning is printed before startup.
# pip install -e .
# alpha-factory --list-agents
# alpha-asi-demo --demo # launch the α‑ASI world‑model UI
# alpha-agi-insight-v1 orchestrator # run the Insight orchestrator
#
# Or install directly from GitHub for a quick test:
# pip install git+https://github.com/MontrealAI/AGI-Alpha-Agent-v0.git@v0.1.0-alpha
# alpha-factory --list-agents
# Automated one-click setup (builds & starts Docker stack)
./alpha_factory_v1/scripts/one_click_install.sh --deploy
# Verify the Ω‑Lattice demo locally
python alpha_factory_v1/demos/alpha_agi_business_3_v1/alpha_agi_business_3_v1.py --loglevel info
# The entrypoint automatically verifies dependencies via `check_env.py`.
Adjust alpha_factory_v1/demos/alpha_asi_world_model/config.yaml to tune the world-model loop. Key options include
env_batch (parallel environments), hidden (latent state size) and mcts_simulations (MCTS rollouts per action).
Insight Browser Demo
A browser-only Pareto explorer lives under
alpha_factory_v1/demos/alpha_agi_insight_v1/insight_browser_v1.
Run npm run build in that directory to generate the dist/ assets
(they are not stored in Git) then open dist/index.html to run the demo locally.
The quick-start guide is available from the
documentation and is copied
to dist/insight_browser_quickstart.pdf during the build so it is available
alongside the compiled assets.
Set window.DEBUG = true before loading the page to expose debugging helpers
such as window.pop.
For evolutionary experiments you can run the optional
evolution worker container
and POST a tarball of agent code to /mutate.
The script prints AGI_INSIGHT_BUS_CERT, AGI_INSIGHT_BUS_KEY and
AGI_INSIGHT_BUS_TOKEN which you can append to your .env file.
.env Setup & Security
Before running the orchestrator, copy alpha_factory_v1/.env.sample to .env and
replace all placeholder values with strong secrets. The sample sets
NEO4J_PASSWORD=REPLACE_ME as a placeholder—generate a random password for
services like Neo4j and Postgres using openssl rand -base64 18 or a similar
tool and never deploy with the defaults. The orchestrator will refuse to
start if NEO4J_PASSWORD remains REPLACE_ME or is missing.
Set API_TOKEN to a strong secret so that the REST API can authenticate
incoming requests. Clients must send Authorization: Bearer <token>.
The server aborts if API_TOKEN equals REPLACE_ME_TOKEN.
API Token Requirement
Before starting the API server or running the test suite, ensure API_TOKEN
is set to a non-default value. The examples in tests/test_api_status.py use
test-token as a reference token for local runs.
Use API_RATE_LIMIT to limit requests per minute per IP (default 60).
If more than 5% of requests return HTTP 429 within a minute, the server calls
utils.alerts.send_alert to report excessive throttling.
Avoid storing private keys directly in .env. Instead set
AGI_INSIGHT_SOLANA_WALLET_FILE to a file containing your hex-encoded wallet
key and keep that file readable only by the orchestrator.
To enable secure gRPC transport set AGI_INSIGHT_BUS_CERT,
AGI_INSIGHT_BUS_KEY and AGI_INSIGHT_BUS_TOKEN. If these values are
omitted and AGI_INSIGHT_ALLOW_INSECURE=1, the bus starts without TLS.
See the documentation
for instructions and example volume mounts.
.env.sample notes that paths on Windows may require quotes (e.g., C:\\path\\to\\file).
Supported Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| OPENAI_API_KEY | (empty) | API key for hosted models. Offline mode is used when empty. |
| OPENAI_TIMEOUT_SEC | 30 | Timeout for OpenAI API requests in seconds. |
| NO_LLM | 0 | Set to 1 to skip the LLM planner even when OPENAI_API_KEY is provided. |
| ALPHA_ASI_LLM_MODEL | gpt-4o-mini | Planner model name used by the world model demo. |
| ALPHA_ASI_SEED | 42 | Deterministic RNG seed for the demo (can also be set via general.seed in config.yaml). |
| ALPHA_ASI_MAX_STEPS | 100000 | Learner steps before auto-stop. |
| ALPHA_ASI_BUFFER_LIMIT | 50000 | Replay-buffer length. |
| ALPHA_ASI_TRAIN_BATCH | 128 | SGD mini-batch size. |
| ALPHA_ASI_MAX_GRID | 64 | Safety clamp on generated mazes. |
| ALPHA_ASI_HOST | 0.0.0.0 | FastAPI bind address for the demo. |
| ALPHA_ASI_PORT | 7860 | FastAPI port for the demo. |
| NEO4J_PASSWORD | REPLACE_ME | Database password required by the orchestrator. |
| RUN_MODE | api | Launch mode for Compose or Helm (api, cli, web). |
| PORT | 8000 | REST API port. |
| AGI_INSIGHT_OFFLINE | 0 | Set to 1 to force local inference models. |
| AGI_INSIGHT_BUS_PORT | 6006 | gRPC bus port used by the demo. |
| AGI_INSIGHT_LEDGER_PATH | ./ledger/audit.db | Path to the local audit ledger. |
| AGI_INSIGHT_SECRET_BACKEND | (empty) | Set to vault, aws or gcp to load secrets from an external manager. |
| VAULT_ADDR/VAULT_TOKEN | (empty) | Connection details for HashiCorp Vault when using the vault backend. |
| AWS_REGION/OPENAI_API_KEY_SECRET_ID | (empty) | AWS Secrets Manager region and secret ID when using the aws backend. |
| GCP_PROJECT_ID/OPENAI_API_KEY_SECRET_ID | (empty) | GCP project and secret name when using the gcp backend. |
| AGI_INSIGHT_BUS_CERT | (empty) | Path to the gRPC bus certificate. |
| AGI_INSIGHT_BUS_KEY | (empty) | Private key matching AGI_INSIGHT_BUS_CERT. |
| AGI_INSIGHT_BUS_TOKEN | (empty) | Shared secret for bus authentication. |
| AGI_INSIGHT_ALLOW_INSECURE | 0 | Set to 1 to run the bus without TLS when no certificate is provided. |
| API_TOKEN | REPLACE_ME_TOKEN | Bearer token required by the REST API. Startup fails if unchanged. |
| API_CORS_ORIGINS | * | Comma-separated list of allowed CORS origins. |
| SANDBOX_CPU_SEC | 2 | CPU time limit for sandboxed code. |
| SANDBOX_MEM_MB | 256 | Memory cap for sandboxed code in MB. |
| MAX_RESULTS | 100 | Maximum stored simulation results. |
| MAX_SIM_TASKS | 4 | Maximum concurrent simulation tasks. |
| IPFS_GATEWAY | https://ipfs.io/ipfs | Base URL for fetching pinned Insight demo runs. Not used for asset downloads. |
| HF_GPT2_BASE_URL | https://huggingface.co/openai-community/gpt2/resolve/main | Base URL for the GPT‑2 checkpoints. |
| PYODIDE_BASE_URL | https://cdn.jsdelivr.net/pyodide/v0.28.0/full | Base URL for the Pyodide runtime files. |
| FETCH_ASSETS_ATTEMPTS | 3 | Download retry count for fetch_assets.py. |
| FETCH_ASSETS_BACKOFF | 1 | Base delay between retries in seconds. |
| OTEL_ENDPOINT | (empty) | OTLP endpoint for anonymous telemetry. |
| SKIP_WEBKIT_TESTS | (empty) | Skip WebKit browser tests when set. |
| ALPHA_FACTORY_ENABLE_ADK | false | Set to true to start the Google ADK gateway. |
| ALPHA_FACTORY_ADK_PORT | 9000 | Port for the ADK gateway when enabled. |
| ALPHA_FACTORY_ADK_TOKEN | (empty) | Optional auth token for the ADK gateway. |
Troubleshooting Asset Downloads
If scripts/fetch_assets.py or npm run fetch-assets returns 401 or 404,
download the checkpoint directly:
python scripts/download_hf_gpt2.py models/gpt2
# Or fetch manually from Hugging Face
curl -O https://huggingface.co/openai-community/gpt2/resolve/main/pytorch_model.bin
curl -O https://huggingface.co/openai-community/gpt2/resolve/main/vocab.json
curl -O https://huggingface.co/openai-community/gpt2/resolve/main/merges.txt
curl -O https://huggingface.co/openai-community/gpt2/resolve/main/config.json
The script pulls the signed demo container, runs a BTC/GLD strategy, prints open
positions and P&L, and exposes the trace‑graph UI at
http://localhost:${TRACE_WS_PORT}.
Need a different pair or port? Use environment variables:
STRATEGY=my_pair PORT_API=8001 TRACE_WS_PORT=9000 bash deploy_alpha_factory_demo.sh
No GPU → falls back to GGML Llama‑3‑8B‑Q4.
No OPENAI_API_KEY → switches to local SBERT + heuristics.
AF_LLM_CACHE_SIZE caps in-memory LLM cache entries (default 1024).
AF_PING_INTERVAL sets the ping frequency in seconds (default 60, minimum 5).
AF_DISABLE_PING_AGENT=true disables the built‑in ping agent.
<a name="61-running-tests"></a>
6.1 · Running Tests 🧪
Unit tests can be executed with the bundled helper script:
python -m alpha_factory_v1.scripts.run_tests
Always run python check_env.py --auto-install beforehand so optional
dependencies like openai_agents and gymnasium are present. Use
ALPHA_FACTORY_FULL=1 to install heavy extras.
The helper validates the target directory, prefers pytest when
available and otherwise falls back to unittest. Ensure all tests pass
before deploying changes.
Install the project in editable mode so tests resolve imports:
pip install -e .
python check_env.py --auto-install # times out after 10 minutes
# Install heavier extras so tests needing torch or faiss work:
ALPHA_FACTORY_FULL=1 python check_env.py --auto-install
The run_tests helper automatically executes python check_env.py --auto-install
before running pytest. When offline, set WHEELHOUSE or pass
--wheelhouse <dir> so packages install from the local wheel cache. The
repository ships with a wheels/ directory that can be used as this cache.
The full test suite relies on optional packages including numpy, torch,
pandas, prometheus_client, gymnasium, playwright, httpx, uvicorn,
git, hypothesis and requests_mock.
Tests that depend on optional heavy packages skip automatically when those
libraries are missing. Set environment variables like SKIP_WEBKIT_TESTS=1
or PYTEST_NET_OFF=1 to bypass browser or network tests if the necessary
dependencies aren't installed.
Wheelhouse Setup
Tests install packages from PyPI unless a local wheelhouse is provided. Build
one from requirements.lock and point WHEELHOUSE to it before verifying the
environment and running the suite:
If network access is unavailable and the variable is unset these commands fail
instead of falling back to PyPI.
Offline or Restricted Environments
Run ./scripts/build_offline_wheels.sh to populate a wheelhouse on a
machine with internet access, then set WHEELHOUSE=<path> before executing
the tests so dependencies install from this local cache.
If npx playwright install fails to download WebKit, set SKIP_WEBKIT_TESTS=1
so browser checks skip gracefully.
Test Runtime
Running pytest may take several minutes on the first run while caches are
created. Execute the suite in verbose mode to see ongoing progress:
pytest -vv
After completion pytest prints a summary such as ### passed in 120.00s.
The suite includes tests/test_api_rate_limit.py which spins up
api_server.app with API_RATE_LIMIT=2 and verifies that exceeding the
limit returns HTTP 429.
<a name="62-marketplace-demo-example"></a>
6.2 · Marketplace Demo Example 🛒
A minimal snippet queues the sample job once the orchestrator is running:
alpha-factory --enabled finance,manufacturing &
python - <<'PY'
import subprocess, time
from alpha_factory_v1.demos import alpha_agi_marketplace_v1 as market
time.sleep(5)
subprocess.run(["bash", str(market.POST_JOB_SCRIPT), str(market.SAMPLE_JOB)], check=True)
marketplace_args = ["python", "-m", "alpha_factory_v1.demos.alpha_agi_marketplace_v1.marketplace", str(market.SAMPLE_JOB)]
subprocess.run(marketplace_args, check=True)
PY
6.2 · Cross-Industry Demo Quick‑Start 🌐
Clone the stable v0.1.0-alpha release:
git clone --branch v0.1.0-alpha https://github.com/MontrealAI/AGI-Alpha-Agent-v0.git
cd AGI-Alpha-Agent-v0/alpha_factory_v1/demos/cross_industry_alpha_factory
# Set AUTO_COMMIT=1 to save generated assets back to the repo
./deploy_alpha_factory_cross_industry_demo.sh
6.3 · Signing Agent Wheels 🔑
Sign wheels dropped into $AGENT_HOT_DIR with the project ED25519 key.
You need OpenSSL to create and verify signatures. Install it with
brew install openssl on macOS or from the
OpenSSL Windows binaries.
Generate <wheel>.whl.sig via:
Add the base64 signature to _WHEEL_SIGS in
alpha_factory_v1/backend/agents/__init__.py. Wheels failing verification are
ignored.
6.4 · Web Dashboard Quick-Start 📊
Launch the local web interface:
uvicorn alpha_factory_v1.demos.alpha_agi_insight_v1.src.interface.api_server:app --reload
streamlit run alpha_factory_v1/demos/alpha_agi_insight_v1/src/interface/web_app.py
# React client
cd alpha_factory_v1/demos/alpha_agi_insight_v1/src/interface/web_client
npm ci # use the lock file for reproducible installs
npm run dev # http://localhost:5173
# build production assets
npm run build
python -m http.server --directory dist 9000
Alternatively run inside Docker:
# build the web client first so `dist/` exists
make build_web
# regenerate protobuf modules and Go stubs
./tools/gen_proto_stubs.sh # updates alpha_factory_v1/core/utils/a2a_pb2.py and tools/go_a2a_client/a2a.pb.go
make compose-up # builds and waits for healthy services
Run ./tools/gen_proto_stubs.sh whenever alpha_factory_v1/core/utils/a2a.proto changes to keep the
Python and Go stubs up to date.
Open http://localhost:8080 in your browser. When RUN_MODE=web, the container
serves the static files from alpha_factory_v1/demos/alpha_agi_insight_v1/src/interface/web_client/dist using python -m http.server. The FastAPI demo also mounts this folder at / when present so the
dashboard is reachable without additional tooling.
Once running, Docker Compose marks the services healthy when:
http://localhost:8000/healthz returns status 200 for the orchestrator container.
http://localhost:8000/status exposes agent heartbeats and restart counts.
Use alpha-agi-insight-v1 agents-status to view the same data from the CLI.
http://localhost:8080/ returns status 200 for the web container.
The dashboard now plots a 3‑D scatter chart of effectiveness vs. risk vs.
complexity from the final population.
If Streamlit isn't installed or you're running on a headless server, use:
to display the forecast results directly in the console.
<a name="7-deployment-recipes"></a>
7 · Deployment Recipes 🍳
The repository bundles a lightweight edge_runner.py helper for running
Alpha‑Factory on air‑gapped or resource‑constrained devices. The script
forwards to alpha_factory_v1.edge_runner and exposes additional flags
like --cycle, --loglevel and --version.
It prints the same warning as the main CLI before launching.
Build the demo containers locally:
cp .env.sample .env # fill in NEO4J_PASSWORD, API_TOKEN and optional PINNER_TOKEN
chmod 600 alpha_factory_v1/.env
cd infrastructure
docker build -t alpha-demo .
docker compose up -d
# Dashboard available at <http://localhost:8080>
The Compose stack restricts the agents worker using Docker resource limits. The
agents service runs with mem_limit: 8g, pids_limit: 512 and
network_mode: none to prevent outbound traffic.
The Helm chart under infrastructure/helm-chart mirrors this Compose
setup:
helm upgrade --install alpha-demo ./infrastructure/helm-chart \
--values ./infrastructure/helm-chart/values.yaml \
--set env.RUN_MODE=web
# Enable persistent storage for the audit ledger
# --set persistence.enabled=true --set persistence.size=5Gi
# → browse to <http://localhost:8080>
values.example.yaml demonstrates typical overrides such as API tokens, service ports and replica counts.
The Helm charts ship with placeholders like NEO4J_PASSWORD and
adminPassword set to REPLACE_ME. Replace these with strong secrets
in values.yaml or via --set before deploying.
Terraform scripts in infrastructure/terraform provide GCP and AWS
examples. Update the placeholder image and networking variables,
then initialise and apply:
cd infrastructure/terraform
terraform init
terraform apply
Prometheus scrapes metrics from the API server at /metrics.
By default traces and metrics print to stdout. To export to a collector such
as Jaeger, set OTEL_EXPORTER_OTLP_ENDPOINT and start Jaeger locally:
docker run -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one
Set OTEL_ENDPOINT to enable anonymous dashboard telemetry. Users are
prompted for consent before any metrics are sent.
Telemetry Queue
Anonymous usage metrics are buffered in the browser under the
telemetryQueue key in localStorage. Each record includes:
ts – the timestamp when the entry was recorded.
session – a deterministic SHA‑256 hash identifying the session.
generations – how many runs were executed.
shares – how many times results were shared.
When the browser is online the queue is flushed to OTEL_ENDPOINT using
navigator.sendBeacon with a fetch fallback. The queue holds at most 100
entries and is persisted across page loads until sent. No personal data or IP
addresses are stored.
Telemetry can be disabled from the Analytics panel by clicking Disable
telemetry. Clearing the telemetryConsent and telemetryQueue entries in
browser storage also stops all transmissions.
<a name="10-safety--security"></a>
10 · Safety & Security 🛡️
The policy runbook outlines sandbox resource limits,
timeout behaviour, required human review and rollback steps.
Operational tips for the governance module reside in the
documentation.
<a name="11-extending-the-mesh"></a>
11 · Extending the Mesh 🔌
from backend.agents.base import AgentBase
class MySuperAgent(AgentBase):
NAME = "super"
CAPABILITIES = ["telemetry_fusion"]
COMPLIANCE_TAGS = ["gdpr_minimal"]
async def run_cycle(self):
...
# setup.py entrypoint
[project.entry-points."alpha_factory.agents"]
super = my_pkg.super_agent:MySuperAgent
pip install . → orchestrator hot‑loads at next boot.
Decimals:18 (ERC‑20 standard; 1 token = 1e18 base units)
Config defaults:token.config.js pins the token wiring for builds and
tests; override with AGIALPHA_ADDRESS / AGIALPHA_DECIMALS environment
variables when deploying to alternate networks.
ERC‑20 Approvals
Staking and job escrow pull funds via transferFrom, so each account must
approve the StakeManager contract before staking or posting a job. $AGIALPHA
uses 18 decimals, meaning 1e18 represents one token.
# Allow the StakeManager to move 100 AGIALPHA for your stake
cast send 0xa61a3b3a130a9c20768eebf97e21515a6046a1fa \
"approve(address,uint256)" $STAKEMANAGER 100e18
# Authorize 50 AGIALPHA to be locked as job escrow
cast send 0xa61a3b3a130a9c20768eebf97e21515a6046a1fa \
"approve(address,uint256)" $STAKEMANAGER 50e18
Replace $STAKEMANAGER with the deployed contract address.
<a name="15-license"></a>
15 · License
This project is distributed under the Apache 2.0 license.
All community members are expected to follow our Code of Conduct.
Please report security issues via the process outlined in our Security Policy.
Release Tweet
🚀 New Alpha-Factory release! Offline dashboard, responsive UI and automated visual tests powered by Percy.
<a name="16-final-note"></a>
16 · Final Note
Please ensure all usage and contributions align with the project's
Apache 2.0 license.
Made with ❤️ by the Alpha‑Factory Agentic Core Team — forging the tools that forge tomorrow.
