Skip to content

About

Multi-language Active Inference framework combining ant-colony-optimization-inspired multi-agent simulation with variational message passing, implemented across 50 programming languages for research and benchmarking.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

4 watching

Forks

Latest commit

Β 

History

203 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

🧠 Active InferAnts

A Multi-Language Active Inference Framework for Advanced AI Research and Applications

License: CC BY-NC-ND 4.0 Python 3.12+ Multi-Language Active Inference

Welcome to Active InferAnts - a comprehensive, multi-language framework that implements Active Inference algorithms across 50 programming languages. This project serves as both a research platform for studying active inference mechanisms and a practical toolkit for building sophisticated AI applications that can learn, adapt, and make decisions in complex environments.

Table of Contents

🎯 Overview

Active InferAnts represents a groundbreaking approach to implementing Active Inference algorithms - a mathematical framework for understanding perception, learning, and decision-making in biological and artificial agents. Our system uniquely combines:

  • Multi-Language Implementation: Core Active Inference algorithms implemented in 50 registered programming languages
  • Ant Colony Optimization: Nature-inspired optimization strategies integrated with Active Inference principles
  • Modular Architecture: Clean separation of concerns across 6 operational phases
  • Research-to-Production Pipeline: From theoretical models to deployable applications

What is Active Inference?

Active Inference is a mathematical framework that explains how biological agents (including humans) perceive, learn, and act in uncertain environments. It proposes that agents minimize "surprise" by constantly updating their beliefs about the world and taking actions to confirm those beliefs.

Why Active InferAnts?

Traditional AI approaches often separate perception, learning, and action. Active Inference unifies these processes under a common mathematical framework, enabling more robust, adaptable, and biologically-plausible AI systems.

Key Innovation: Multi-Language Approach

By implementing the same algorithms in multiple programming languages, we ensure:

  • Algorithm Correctness: Cross-validation across language implementations
  • Performance Benchmarking: Direct comparison of language capabilities
  • Accessibility: Choose the best language for your specific use case
  • Educational Value: Learn Active Inference concepts across different programming paradigms

✨ Key Features

πŸ€– Core AI Capabilities

  • Advanced Active Inference: State-of-the-art implementations of variational message passing and belief propagation
  • Ant Colony Optimization: Nature-inspired algorithms for complex optimization problems
  • Multi-Agent Systems: Distributed inference across multiple agents with pheromone-based communication
  • Adaptive Learning: Real-time belief updating and policy optimization
  • Uncertainty Quantification: Robust handling of environmental uncertainty and sensor noise

πŸ—οΈ Architecture & Design

  • Modular Pipeline: 6-phase operational framework (Prepare β†’ Operate β†’ Measure β†’ Report β†’ Follow-up β†’ API)
  • Multi-Language Support: 50 programming languages with consistent APIs
  • Plugin Architecture: Extensible design for custom algorithms and integrations
  • Configuration Management: Flexible parameter system with JSON-based configuration
  • Security-First: Built-in encryption, hashing, and secure communication utilities

πŸ”§ Technical Features

  • High Performance: Parallel processing and GPU acceleration support
  • Cross-Platform: Runs on Linux, macOS, Windows, and cloud environments
  • Real-Time Processing: Low-latency inference for time-critical applications
  • Scalable Architecture: From edge devices to distributed cloud deployments
  • Memory Efficient: Optimized data structures for large-scale problems

πŸ“Š Analysis & Visualization

  • Rich Visualizations: Interactive plots for belief states, free energy landscapes, and agent behavior
  • Performance Monitoring: Real-time metrics and comprehensive benchmarking tools
  • Debugging Support: Detailed logging and state inspection capabilities
  • Report Generation: Automated generation of analysis reports and performance summaries

πŸ”Œ Integration Ecosystem

  • REST APIs: FastAPI-based knowledge management and inference services
  • Knowledge Storage: SQLAlchemy primary store, SQLite by default, with optional best-effort MongoDB, Redis, Neo4j and Elasticsearch secondaries.
  • Third-Party Integrations: BPMN, Coda, ActivityPub, Nostr, Kafka, and more
  • Container Ready: Docker support for easy deployment and scaling

🧬 Model specification (GNN)

The framework's continuous Gaussian agent (active_infer_ants/agent.py) is specified in gnn/gaussian_agent.gnn.md in Generalized Notation Notation (GNN): the identity dynamics and readout, the process and sensory covariances that carry the prior_precision / sensory_precision parameters, the preferred-state prior, and the infer() posterior update.

The specification is validated against the GNN revision pinned in gnn/upstream.json (schema gnn-importer-pin/v1: ActiveInferenceInstitute/Generalized_Notation_Notation at v5.1.0, commit 75c834bd8519dc7b5adc4d24f16bf393cfd1ecdf), read from that pinned commit (via git archive) rather than from the GNN checkout's working tree:

./run.sh gnn    # provisions the pinned parser, runs the shared reader, validates the spec

The arm provisions the pinned commit into a directory it creates under the gitignored .cache/gnn/<pin commit> (or a fresh sibling if that path is occupied and unusable), then runs the shared GNN-FEP reader from that environment as python -m gnn.importers check --repo .: the pin, its shape and the specification's syntax are validated by the reader the pinned revision ships, and this repository carries no copy of it. It then runs scripts/validate_gnn_spec.py and the gnn-marked tests in tests/test_gnn_conformance.py. A GNN_ROOT you set yourself is read-only: the arm verifies it contains the pin and a runtime, and refuses rather than fetching, installing or deleting inside it (that path may be another repository's working copy). The script parses the specification with the pinned GNN extractor and checks the extracted matrices and parameters against the framework agent, including that infer() performs exactly the declared Gaussian posterior update; the tests assert the pin record through the shared reader, the specification's required sections, the declared dimensions, and that a mutated model is rejected. The module is marked gnn, so ./run.sh test-fast needs no GNN checkout; when GNN_ROOT selects a checkout explicitly, an unusable checkout fails rather than skips. When editing the specification, start from GNN's Start Here, framework integration guide, and syntax reference. For the wider picture (the adoption patterns sibling repositories use, pin discipline, and the drift guard these checks implement), see GNN's downstream adoption guide.

Required local GNN check

The main ruleset requires gnn conformance (local) on the current PR head. The hosted gnn conformance (pinned) job remains optional. Prepare a detached validation checkout at the PR head with Python 3.12 and uv. In GitVault, use its repository admission rules to prepare that checkout and the pinned parser. Confirm that the checkout matches the open PR.

set -eu
repo=ActiveInferenceInstitute/Active_InferAnts
: "${PR_NUMBER:?Set PR_NUMBER}"
pr_head=$(gh pr view "$PR_NUMBER" --repo "$repo" --json headRefOid --jq .headRefOid </dev/null)
test "$(git rev-parse HEAD </dev/null)" = "$pr_head"
test -z "$(git status --porcelain=v1 --untracked-files=all </dev/null)"

Prepare the locked project environment with UV_PYTHON=3.12 ./run.sh setup and a read-only parser checkout at the commit in gnn/upstream.json. The parser Python needs numpy, defusedxml, and PyYAML. The GNN arm can also provision its own parser cache before an offline run. With both environments and the uv cache prepared, export the absolute GNN_ROOT and GNN_PYTHON paths and run the same arms as the hosted job, locally.

: "${GNN_ROOT:?Set GNN_ROOT to the prepared parser checkout}"
: "${GNN_PYTHON:?Set GNN_PYTHON to its interpreter}"
export GNN_ROOT GNN_PYTHON
UV_PYTHON=3.12 UV_OFFLINE=true ./run.sh setup lint docs test-fast gnn

For a publishable GitVault receipt, run those five arms in order through execute --classification test. Prepare the intent using GitVault's docs/EXECUTE.md and docs/EXECUTION-INTENT.md. Bind the clean PR revision, run.sh, uv.lock, and the pin file. Pass the parser paths to the qualified child and set them there. Use the child's GITVAULT_EXECUTION_OUTPUT for the fast and GNN reports. The GNN suite must execute tests with zero skips, failures, or errors. Preserve the report and the source-bound exit receipt.

Publish the local GNN result

An authorized maintainer uses the configured GitVault launcher with the mapped Institute identity and the state write class enabled. Set VAULT to that launcher's absolute path, PR_NUMBER to the pull request number, and GNN_EXIT_RECEIPT to the governed run's exit.json. Review the passing gate output and its nonempty, zero-skip test report before planning success.

set -eu
repo=ActiveInferenceInstitute/Active_InferAnts
context='gnn conformance (local)'
: "${VAULT:?Set VAULT}" "${PR_NUMBER:?Set PR_NUMBER}" "${GNN_EXIT_RECEIPT:?Set GNN_EXIT_RECEIPT}"
tested_head=$(jq -er --arg repo "$repo" '
  .payload | select(.classification == "test" and .outcome == "SUCCEEDED"
    and .returncode == 0 and .source_unchanged == true and .binding.source == $repo
    and .descendants.sample_errors == 0 and .descendants.remaining == [])
  | .binding.revision | select(test("^[0-9a-f]{40}$"))
' "$GNN_EXIT_RECEIPT")
test "$(gh pr view "$PR_NUMBER" --repo "$repo" --json headRefOid --jq .headRefOid </dev/null)" = "$tested_head"

digest=$(shasum -a 256 "$GNN_EXIT_RECEIPT")
status_parameters=$(jq -nc --arg repo "$repo" --arg head "$tested_head" --arg context "$context" \
  --arg digest "${digest%% *}" '{
    repository:$repo, expected_commit:$head, context:$context, state:"success",
    description:("Local pinned GNN checks passed. Receipt SHA-256 " + $digest[:16])
  }')
plan=$("$VAULT" plan github-status --parameters "$status_parameters" </dev/null)
plan_id=$(printf '%s\n' "$plan" | jq -er .github)
confirmation=$(printf '%s\n' "$plan" | jq -er .confirmation)
"$VAULT" github-apply --plan "$plan_id" </dev/null

Review the repository, commit, context, and exact confirmation phrase in the plan. In the same shell, recheck the live PR head before applying. Confirm that GitHub reports the local context as a passing required check. A new head needs a fresh run and publication.

test "$(gh pr view "$PR_NUMBER" --repo "$repo" --json headRefOid --jq .headRefOid </dev/null)" = "$tested_head"
"$VAULT" github-apply --plan "$plan_id" --apply --confirm "$confirmation" </dev/null
gh api "repos/$repo/commits/$tested_head/status" </dev/null |
  jq -e --arg head "$tested_head" --arg context "$context" '
    .sha == $head and any(.statuses[]; .context == $context and .state == "success")'
test "$(gh pr view "$PR_NUMBER" --repo "$repo" --json headRefOid --jq .headRefOid </dev/null)" = "$tested_head"
gh pr checks "$PR_NUMBER" --repo "$repo" --required --json name,bucket </dev/null |
  jq -e --arg context "$context" 'any(.[]; .name == $context and .bucket == "pass")'

πŸ”— Related repositories

  • Generalized_Notation_Notation β€” the specification and implementation core this repository's agent spec is pinned to.
  • ants β€” the 2021 ant-colony foraging model this framework grew out of; it owns that model's GNN specification.
  • Active_Skillference β€” the micro-learning platform whose discrete agent kernel is specified in its own gnn/ directory.

Each model has one canonical home: this repository specifies its framework agent, while the ant-colony MDP and the discrete curriculum agent live with the repositories that implement them.

πŸ“š Documentation

The modular documentation hub lives in docs/ and is published with MkDocs (mkdocs.yml). Every document is indexed from docs/documentation-index.md; the rendered entry point is docs/index.md.

Start here Document
New to Active Inference Active Inference Primer
Run the code Getting Started
Build an agent Your First Agent
Understand the pipeline Pipeline Overview
Use the APIs Knowledge API Β· MetaInformAnt API
Test and verify Testing Strategy
Run the checks Run Guide (arms, lint surface, CI mapping)
Find a document Documentation Index Β· Gate metrics

Build the site locally with ./run.sh docs (or mkdocs serve for a live preview; both come from the docs extra installed by ./run.sh setup).

πŸš€ Quick Start

Get up and running with Active InferAnts in under 5 minutes:

Option 1: Run All Language Implementations

# Clone the repository
git clone https://github.com/ActiveInferenceInstitute/Active_InferAnts.git
cd Active_InferAnts

# Set up environment and run all implementations
python3 0_CONTEXT/Computer_Languages/master_controller.py setup
python3 0_CONTEXT/Computer_Languages/master_controller.py run

Option 2: Run Python Implementation Only

# Basic Active Inference example
from active_infer_ants import InferenceModel

# Initialize with default configuration
model = InferenceModel()

# Run inference for 1000 iterations
results = model.run(max_iterations=1000)

# Visualize results
model.visualize(results)

Option 3: Start the Knowledge API

# Start the FastAPI knowledge management service
cd 6_API && python3 Knowledge_API.py

# API will be available at http://localhost:8000
# Interactive docs at http://localhost:8000/api/docs

Option 4: Run Benchmarks

# Run comprehensive performance benchmarks
python3 0_CONTEXT/Computer_Languages/master_controller.py benchmark

# View status dashboard
python3 0_CONTEXT/Computer_Languages/master_controller.py status

πŸ“¦ Installation

Prerequisites

  • Python 3.12+ (for core functionality and master controller)
  • Git (for cloning and version control)
  • 50 Programming Languages (optional, for multi-language implementations)

Core Installation

# Clone the repository
git clone https://github.com/ActiveInferenceInstitute/Active_InferAnts.git
cd Active_InferAnts

# Install Python dependencies
pip install -r requirements.txt

# Optional: Install development dependencies
pip install -r requirements-dev.txt

Multi-Language Setup

For full multi-language support, install the required compilers and interpreters:

# Use the automated setup script
python3 0_CONTEXT/Computer_Languages/master_controller.py setup

# Or manually install language-specific dependencies
python3 0_CONTEXT/Computer_Languages/config_manager.py --all

Docker Installation

# Build the Docker image
docker build -t active-inferants .

# Run the container
docker run -p 8000:8000 active-inferants

Development Installation

# One environment spec, and the gate that uses it
./run.sh setup

# Install the pre-commit hook (it calls ./run.sh lint)
pre-commit install

# Set up all language environments
python3 0_CONTEXT/Computer_Languages/master_controller.py setup

System Requirements

  • Minimum: 4GB RAM, 2GB disk space
  • Recommended: 16GB RAM, 10GB disk space for full multi-language setup
  • GPU: Optional, CUDA-compatible GPU for accelerated computations

Dependencies Overview

  • Core: NumPy, SciPy, Matplotlib, pandas, seaborn
  • APIs: FastAPI, uvicorn, SQLAlchemy, Pydantic
  • Databases: SQLite (default) with optional PostgreSQL, MongoDB, Redis, Neo4j, Elasticsearch backends
  • Visualization: Matplotlib, Plotly, Seaborn
  • Security: cryptography, argon2-cffi

πŸ› οΈ Usage

Basic Active Inference

from active_infer_ants import ActiveInferenceAgent, Environment

# Create an environment
env = Environment(config={"complexity": 3, "uncertainty": 0.2})

# Initialize an Active Inference agent
agent = ActiveInferenceAgent(
    sensory_precision=5,
    prior_precision=2,
    learning_rate=0.1
)

# Run inference loop
for iteration in range(1000):
    # Sense the environment
    observation = env.observe()

    # Update beliefs and plan actions
    action = agent.infer(observation)

    # Execute action and get reward
    reward = env.step(action)

    # Learn from the experience
    agent.learn(reward)

# Visualize final beliefs
agent.visualize_beliefs()

Multi-Agent Simulation

from active_infer_ants import AntColony, PheromoneNetwork

# Create a colony of 50 agents
colony = AntColony(n_agents=50)

# Initialize pheromone communication network
pheromones = PheromoneNetwork(colony.agents)

# Run distributed optimization
for iteration in range(100):
    # Each agent performs active inference
    actions = colony.parallel_inference()

    # Update pheromone trails
    pheromones.update_trails(actions)

    # Agents learn from collective experience
    colony.learn_from_colony(pheromones.get_pheromone_map())

# Analyze emergent behavior
colony.analyze_emergent_behavior()

Using the Master Controller

# Run all language implementations
python3 0_CONTEXT/Computer_Languages/master_controller.py run

# Run specific language implementation
python3 0_CONTEXT/Computer_Languages/master_controller.py run python

# Run comprehensive benchmarks
python3 0_CONTEXT/Computer_Languages/master_controller.py benchmark

# Generate detailed reports
python3 0_CONTEXT/Computer_Languages/master_controller.py report

# View interactive status dashboard
python3 0_CONTEXT/Computer_Languages/master_controller.py status

API Usage

import requests

# Store knowledge
response = requests.post(
    "http://localhost:8000/api/knowledge/",
    json={
        "source": "experiment_001",
        "content": {"accuracy": 0.95, "parameters": {"lr": 0.01}}
    },
    headers={"X-API-Key": "your-secret-key"}
)

# Retrieve knowledge
knowledge = requests.get(
    "http://localhost:8000/api/knowledge/experiment_001",
    headers={"X-API-Key": "your-secret-key"}
).json()

Configuration

# Using JSON configuration
config = {
    "max_iterations": 1000,
    "learning_rate": 0.1,
    "exploration_factor": 0.3,
    "visualization_enabled": True,
    "output_directory": "./results"
}

# Load from file
with open('config.json', 'r') as f:
    config = json.load(f)

# Initialize with custom config
agent = ActiveInferenceAgent.from_config(config)

Advanced Examples

For comprehensive examples, see:

πŸ—οΈ Project Architecture

Core Operational Pipeline

Active InferAnts follows a 6-phase operational pipeline that transforms theoretical Active Inference models into deployable applications:

graph LR
    A[0_CONTEXT] --> B[1_PREPARE]
    B --> C[2_OPERATE]
    C --> D[3_MEASURE]
    D --> E[4_REPORT]
    E --> F[5_FOLLOWUP]
    F --> G[6_API]
Loading

Core Directory Structure

  • 0_CONTEXT/ - Research context, specifications, and multi-language implementations

  • 1_PREPARE/ - Data preparation, configuration, and foundational components

    • configs/ - Configuration management system
    • General/ - Core Active Inference algorithms
    • Methods/ - Research methods and theory translation
    • Things/ - Agent implementations and digital twins
    • Utils/ - Security, compression, and utility modules
  • 2_OPERATE/ - Runtime execution and simulation management

  • 3_MEASURE/ - Analysis, statistics, and performance measurement

  • 4_REPORT/ - Reporting and communication systems

  • 5_FOLLOWUP/ - Continuous improvement and follow-up actions

  • 6_API/ - REST APIs and external interfaces

  • 9_OTHER/ - Third-party integrations and specialized modules

    • ActivityPub/ - ActivityPub protocol integration
    • BPMN/ - Business Process Model integration
    • Coda/ - Coda platform integration
    • FOIA/ - Freedom of Information Act data processing
    • Github/ - GitHub integration utilities
    • HoloChain/ - Holochain distributed ledger integration
    • Kafka/ - Apache Kafka integration
    • Nostr/ - Nostr protocol integration
    • TheBrain/ - TheBrain mind mapping integration

Multi-Language Support

Active InferAnts implements Active Inference algorithms in 50 programming languages, ensuring:

  • Algorithm Validation: Cross-language verification of mathematical correctness
  • Performance Benchmarking: Direct comparison across language implementations
  • Accessibility: Choose the optimal language for your specific requirements
  • Educational Value: Learn Active Inference across different programming paradigms

Supported Languages:

  • Systems Languages: Rust, C++, C, Zig, Go, Nim, Odin
  • Scientific Computing: Python, R, Julia, MATLAB
  • Functional Languages: Haskell, OCaml, F#, Elixir, Erlang, Clojure
  • Scripting Languages: JavaScript, TypeScript, Ruby, Perl, PHP, Lua
  • Enterprise Languages: Java, C#, Scala, Kotlin
  • Specialized: Assembly, Brainfuck, Jock, V, Prolog, Fortran, Pascal, SQL

Key Files:

πŸ”Œ APIs

Knowledge Management API

A FastAPI knowledge service with synchronous SQLAlchemy access. SQLite is the default primary; configured synchronous clients provide optional best-effort MongoDB, Redis, Neo4j and Elasticsearch operations.

SQL is authoritative. Reads/lists query SQL, not Redis; Redis is a secondary copy, not a read-through cache. SQL and secondary operations are not one atomic transaction. Secondary failures can leave missing or stale copies; successful primary writes do not guarantee real-time consistency or convergence.

Features: SQL-first CRUD and pagination; optional secondary stores; environment-enabled API-key authentication on every knowledge CRUD/list route; OpenAPI/Swagger and ReDoc. No search/analytics endpoints or distributed transaction are exposed.

Endpoints:

  • POST /api/knowledge/ - Create knowledge entry
  • GET /api/knowledge/{source} - Retrieve knowledge
  • PUT /api/knowledge/{source} - Update knowledge
  • DELETE /api/knowledge/{source} - Delete knowledge
  • GET /api/knowledge/ - List entries using skip/limit pagination.

Meta-Information API

Advanced API for managing meta-information about Active Inference processes and agents:

Key Features:

  • Process Tracking: Monitor inference processes in real-time
  • Agent Management: Control and monitor multiple agents
  • Performance Metrics: Real-time performance monitoring
  • Configuration Management: Dynamic parameter adjustment
  • Health Checks: System health and status monitoring

πŸ§ͺ Testing & Quality Assurance

Comprehensive Test Suite

Active InferAnts includes a sophisticated testing framework that ensures reliability across all implementations:

Key Components:

  • Multi-Language Testing: Automated testing across 50 programming languages
  • Performance Benchmarking: Cross-language performance comparisons
  • Algorithm Validation: Mathematical correctness verification
  • Integration Testing: End-to-end system validation
  • Continuous Integration: Automated testing pipelines

Test Categories:

  • Unit Tests: Individual algorithm and function testing
  • Integration Tests: Component interaction validation
  • Performance Tests: Benchmarking and profiling
  • Cross-Language Tests: Consistency validation across implementations
  • Regression Tests: Preventing functionality degradation

Running Tests

The repository's single check entry point is ./run.sh; each arm is the exact command CI runs (see docs/RUN_GUIDE.md):

./run.sh setup        # one locked environment: uv sync --locked --extra dev --extra docs
./run.sh lint         # ruff (maintained surface) + compile sweep of every tracked source
./run.sh test-fast    # pytest -m "not gnn"
./run.sh test-full    # pytest (adds the gnn-marked conformance module)
./run.sh docs         # mkdocs --strict, relative links, generated docs current
./run.sh gnn          # pinned GNN parser + specification conformance
./run.sh gate         # lint, test-fast, docs, gnn β€” everything, nothing twice

The multi-language implementation suites remain separate, and are unchanged by the gate:

# Run all language implementations with testing
python3 0_CONTEXT/Computer_Languages/master_controller.py test

# Run specific language tests
python3 0_CONTEXT/Computer_Languages/master_controller.py test python

# Run comprehensive benchmark suite
python3 0_CONTEXT/Computer_Languages/test_suite.py

Quality Metrics

  • Code Coverage: unit tests cover the core active_infer_ants package, both REST APIs, and the correctness/security fixes (see tests/); no coverage percentage is claimed. Run ./run.sh test-full.
  • Correctness: every tracked Python source is compile-checked by ./run.sh lint (no syntax errors)
  • Linting: ./run.sh lint is green on the maintained surface; the multi-language corpus is outside it (counts in docs/_generated/gate_metrics.md)
  • Documentation: ./run.sh docs builds the MkDocs hub strictly and checks relative links; FastAPI generates the API OpenAPI/Swagger
  • Security: security fixes are covered by the test suite (see tests/)
  • Measured numbers: per-arm wall times and test counts live in docs/_generated/gate_metrics.md, generated by scripts/docgen/gate_metrics.py

πŸ“Š Performance & Benchmarking

Benchmarking Framework

Comprehensive performance analysis across all language implementations:

# Run performance benchmarks
python3 0_CONTEXT/Computer_Languages/master_controller.py benchmark

# Generate performance reports
python3 0_CONTEXT/Computer_Languages/master_controller.py report

# View interactive performance dashboard
python3 0_CONTEXT/Computer_Languages/status_dashboard.sh

Performance Metrics

  • Execution Time: Comparative analysis across languages
  • Memory Usage: Peak and average memory consumption
  • Scalability: Performance scaling with problem size
  • Accuracy: Algorithm correctness and convergence rates
  • Resource Efficiency: CPU and GPU utilization patterns

Optimization Features

  • Parallel Processing: Multi-core and distributed execution
  • GPU Acceleration: CUDA and OpenCL support where applicable
  • Memory Optimization: Efficient data structures and caching
  • Algorithm Tuning: Automatic parameter optimization
  • Resource Monitoring: Real-time performance tracking

πŸ”§ Development

Development Workflow

# Set up the development environment from uv.lock (uv 0.13.7)
./run.sh setup

# Run the gate: lint, fast tests, docs, GNN conformance
./run.sh gate

# Individual arms
./run.sh lint
./run.sh test-fast
./run.sh docs

# Re-measure the arms and rewrite docs/_generated/gate_metrics.md
./run.sh metrics

# Run development server
python3 6_API/Knowledge_API.py

Code Quality Tools

  • Linting: Ruff (lint + format), pinned in the dev extra and run by ./run.sh lint; the pre-commit hook calls the same arm
  • Type Checking: none configured β€” annotations are documentation, not a gate
  • Testing: pytest, selected by the gnn marker so ./run.sh test-fast needs no GNN checkout
  • Documentation: MkDocs for the docs/ hub, built strictly by ./run.sh docs; FastAPI-generated OpenAPI for the APIs
  • CI/CD: GitHub Actions runs the same arms (.github/workflows/ci.yml, Python 3.12–3.14)

Contributing Guidelines

  1. Fork and Clone: Fork the repository and create a feature branch
  2. Code Standards: Follow PEP 8 and project-specific guidelines
  3. Testing: Add comprehensive tests for new features
  4. Documentation: Update documentation for any new functionality
  5. Cross-Language Consistency: Ensure implementations work across all supported languages
  6. Performance: Include performance benchmarks for significant changes

Development Commands

# Clean all outputs and caches
python3 0_CONTEXT/Computer_Languages/master_controller.py clean

# Check dependencies
python3 0_CONTEXT/Computer_Languages/config_manager.py --all

# Install a language's dependencies
python3 0_CONTEXT/Computer_Languages/config_manager.py --install <language>

# Generate comprehensive reports
python3 0_CONTEXT/Computer_Languages/master_controller.py report

🚨 Troubleshooting

Common Issues and Solutions

Installation Issues

Problem: Missing dependencies after installation

# Solution: Run dependency check and installation
python3 0_CONTEXT/Computer_Languages/config_manager.py --all
python3 0_CONTEXT/Computer_Languages/master_controller.py setup

Problem: Permission denied when running scripts

# Solution: Make scripts executable
chmod +x 0_CONTEXT/Computer_Languages/run_all.sh
chmod +x 0_CONTEXT/Computer_Languages/status_dashboard.sh

Runtime Issues

Problem: API server fails to start

# Check database connections
python3 -c "import redis; print('Redis OK')"  # Test Redis
python3 -c "import pymongo; print('MongoDB OK')"  # Test MongoDB

# Check configuration
cat config.json

Problem: Memory errors during large simulations

# Reduce simulation parameters
{
    "max_iterations": 500,  # Reduce from 1000
    "memory_limit": "4GB",
    "parallel_processes": 2  # Reduce parallelism
}

Multi-Language Issues

Problem: Specific language implementation fails

# Run individual language test
python3 0_CONTEXT/Computer_Languages/master_controller.py run <language>

# Check language-specific dependencies
python3 0_CONTEXT/Computer_Languages/config_manager.py --install <language>

Problem: Performance inconsistency across languages

# Run benchmark comparison
python3 0_CONTEXT/Computer_Languages/master_controller.py benchmark

# Check system resources
python3 0_CONTEXT/Computer_Languages/status_dashboard.sh

Debug Mode

Enable detailed logging for troubleshooting:

# Set debug logging
export LOG_LEVEL=DEBUG
python3 0_CONTEXT/Computer_Languages/master_controller.py run

# View detailed logs
tail -f 0_CONTEXT/Computer_Languages/test_results/test_suite.log

Getting Help

  1. Check Existing Issues: Search GitHub Issues
  2. Run Diagnostics: Use the built-in status dashboard
  3. Review Documentation: Check detailed docs
  4. Community Support: Join our Discord community

🀝 Contributing

We welcome contributions from researchers, developers, and enthusiasts! Here's how to get involved:

Ways to Contribute

  • πŸ› Bug Reports: Found a bug? Open an issue
  • πŸ’‘ Feature Requests: Have an idea? Submit a feature request
  • πŸ”§ Code Contributions: Ready to code? See our development workflow below
  • πŸ“š Documentation: Help improve documentation and tutorials
  • πŸ§ͺ Testing: Add test cases or improve test coverage
  • 🌐 Language Ports: Implement Active Inference in a new programming language

Development Workflow

  1. Fork and Clone

    git clone https://github.com/your-username/Active_InferAnts.git
    cd Active_InferAnts
    git checkout -b feature/your-amazing-feature
  2. Set Up Development Environment

    python3 0_CONTEXT/Computer_Languages/master_controller.py setup
    ./run.sh setup
    pre-commit install
  3. Make Your Changes

    • Follow our coding standards
    • Add comprehensive tests
    • Update documentation
    • Ensure cross-language consistency
  4. Test Your Changes

    # Run the gate: lint, test-fast, docs, GNN conformance
    ./run.sh gate
    
    # Multi-language suites and benchmarks
    python3 0_CONTEXT/Computer_Languages/master_controller.py test
    python3 0_CONTEXT/Computer_Languages/master_controller.py benchmark
  5. Submit Your Contribution

    git add .
    git commit -m "feat: add amazing new feature"
    git push origin feature/your-amazing-feature

    Then create a pull request

Contribution Guidelines

  • Code Standards: Follow PEP 8 for Python, and equivalent standards for other languages
  • Testing: Maintain >90% test coverage for new code
  • Documentation: Update relevant documentation for any new functionality
  • Performance: Include benchmarks for performance-critical changes
  • Cross-Language: Ensure new features work across supported languages
  • Security: Follow security best practices and run security checks

Recognition

Contributors are recognized through:

  • Author credits in release notes
  • Contributor spotlight in our newsletter
  • Exclusive contributor swag
  • Speaking opportunities at conferences

Communication

πŸ“„ License

Active InferAnts is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) license. This license allows you to:

  • βœ… Share: Copy and redistribute the material in any medium or format for non-commercial purposes only
  • βœ… Attribution: You must give appropriate credit, provide a link to the license, and indicate if changes were made

Restrictions

  • ❌ No Commercial Use: You may not use the material for commercial purposes
  • ❌ No Derivatives: You may not remix, transform, or build upon the material
  • ❌ No Additional Restrictions: You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits

Attribution Requirements

When using or sharing this work, you must:

  1. Credit: Provide attribution to "Active InferAnts" and link to the original repository
  2. License Notice: Include the license text or a link to the license
  3. Indicate Changes: Clearly indicate if you made any changes to the material
  4. Link: Include a URI or hyperlink to the material to the extent reasonably practicable

Example Attribution

"Active InferAnts" by Active Inference Institute (@docxology unless otherwise specified) is licensed under CC BY-NC-ND 4.0

Third-Party Licenses

This project includes components with the following licenses:

  • Python Dependencies: Various open-source licenses (see requirements.txt)
  • Multi-Language Runtimes: Respective language runtime licenses
  • Database Components: PostgreSQL (PostgreSQL License), MongoDB (SSPL), etc.

Important Note: The CC BY-NC-ND 4.0 license applies to the Active InferAnts framework and documentation. Third-party components may have different licenses that allow more permissive use. Always check individual component licenses for redistribution rights.

For detailed license information, see LICENSE and the contribution guide for third-party component notes.

πŸ™ Acknowledgments

Research Foundations

Active InferAnts builds upon groundbreaking research in Active Inference and swarm intelligence:

  • Active Inference Theory: Karl Friston, Rafal Bogacz, and the broader Active Inference research community
  • Ant Colony Optimization: Marco Dorigo, Thomas StΓΌtzle, and swarm intelligence researchers
  • Free Energy Principle: Foundational work on predictive coding and active inference
  • Multi-Language Research: Cross-language algorithm validation and performance analysis

Technical Contributors

Special thanks to our core development team and contributors who have made this project possible through their expertise in:

  • Machine Learning & AI: Advanced algorithm implementation and optimization
  • Multi-Language Development: Cross-platform implementation and maintenance
  • Systems Architecture: Scalable system design and performance engineering
  • Research Software Engineering: Best practices in scientific software development

Community & Support

We gratefully acknowledge:

  • Beta Testers: Early adopters who provided valuable feedback
  • Code Contributors: Developers who contributed implementations and improvements
  • Research Collaborators: Academic partners who validated our approaches
  • Open Source Community: The broader community enabling this work

Funding & Support

This project has been supported by:

  • Active Inference Institute: Research funding and infrastructure
  • Open Source Grants: Community contributions and sponsorships
  • Academic Partnerships: Collaborative research initiatives

πŸ“ž Contact & Community

Get In Touch

Support Channels

Channel Purpose
πŸ› GitHub Issues Bug reports & technical issues
πŸ’¬ GitHub Discussions Questions & community support
πŸ’» Discord Real-time chat & community
πŸ“§ Email Business & partnership inquiries

Community Guidelines

  • Be Respectful: Maintain a welcoming environment for all participants
  • Stay On Topic: Keep discussions relevant to Active Inference and related topics
  • Share Knowledge: Help others learn and contribute to the community
  • Follow the Contribution Guide: See docs/guides/contributing.md

Research Collaboration

We're always interested in collaborating with:

  • Research Institutions: Joint research projects and publications
  • Industry Partners: Real-world applications and deployments
  • Educational Organizations: Curriculum development and teaching resources
  • Open Source Projects: Integration and cross-project collaboration

🧠 Active InferAnts - Bridging the gap between theoretical Active Inference and practical AI applications through multi-language implementation and rigorous validation.

Built with ❀️ by the Active Inference research community

⬆️ Back to Top

InstituteOS sidecar

This repository carries a committed .aii/ sidecar with curated InstituteOS metadata (aii-sidecar/v1): category, maturity, ecosystem relations, key artifacts, provenance, and portable tasks. It is read by InstituteOS tooling and does not affect the project's build or runtime.

About

Multi-language Active Inference framework combining ant-colony-optimization-inspired multi-agent simulation with variational message passing, implemented across 50 programming languages for research and benchmarking.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages