A Multi-Language Active Inference Framework for Advanced AI Research and Applications
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.
- π§ Active InferAnts
- Table of Contents
- π― Overview
- β¨ Key Features
- π Documentation
- π Quick Start
- π¦ Installation
- π οΈ Usage
- ποΈ Project Architecture
- π APIs
- π§ͺ Testing & Quality Assurance
- π Performance & Benchmarking
- π§ Development
- π¨ Troubleshooting
- π€ Contributing
- π License
- π Acknowledgments
- π Contact
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
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.
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.
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
- 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
- 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
- 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
- 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
- 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
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 specThe 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.
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 gnnFor 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.
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/nullReview 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")'- 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.
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).
Get up and running with Active InferAnts in under 5 minutes:
# 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# 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)# 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# 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- Python 3.12+ (for core functionality and master controller)
- Git (for cloning and version control)
- 50 Programming Languages (optional, for multi-language implementations)
# 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.txtFor 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# Build the Docker image
docker build -t active-inferants .
# Run the container
docker run -p 8000:8000 active-inferants# 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- 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
- 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
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()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()# 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 statusimport 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()# 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)For comprehensive examples, see:
1_PREPARE/Things/pymdp_Ant_1.py- Basic PyMDP implementation0_CONTEXT/Computer_Languages/Python/- Python implementation details6_API/Knowledge_API.py- Full API implementation0_CONTEXT/Computer_Languages/test_suite.py- Testing framework
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]
-
0_CONTEXT/- Research context, specifications, and multi-language implementationsComputer_Languages/- 50 language implementationsspecs_and_prompts/- System specifications and promptsSystems/- Specialized Active Inference systemsREADME.md- Language implementation guide
-
1_PREPARE/- Data preparation, configuration, and foundational components -
2_OPERATE/- Runtime execution and simulation managementcognitive_utilities.py- Core cognitive functionsexecute_Simulation.py- Simulation orchestrationplan_Simulation.py- Simulation planningrender_Simulation.py- Visualization and rendering
-
3_MEASURE/- Analysis, statistics, and performance measurementcategorization.py- Result categorizationpoly_functor.py- Advanced mathematical analysisstatistics.py- Statistical analysis toolssummarize.py- Automated summarization
-
4_REPORT/- Reporting and communication systemsexecute_report.py- Provider-dependent asynchronous reporting orchestration; real providers are not bundled.specify_report.py- Report specifications
-
5_FOLLOWUP/- Continuous improvement and follow-up actionsexecute_followup.py- Provider-dependent follow-up orchestration; real services are not bundled.specify_followup.py- Follow-up planning
-
6_API/- REST APIs and external interfacesKnowledge_API.py- Synchronous SQL-first knowledge API with best-effort secondary stores.MetaInformAnt_API.py- Meta-information API
-
9_OTHER/- Third-party integrations and specialized modulesActivityPub/- ActivityPub protocol integrationBPMN/- Business Process Model integrationCoda/- Coda platform integrationFOIA/- Freedom of Information Act data processingGithub/- GitHub integration utilitiesHoloChain/- Holochain distributed ledger integrationKafka/- Apache Kafka integrationNostr/- Nostr protocol integrationTheBrain/- TheBrain mind mapping integration
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:
master_controller.py- Central orchestrationrun_all.sh- Multi-language runnertest_suite.py- Comprehensive testing frameworkconfig_manager.py- Dependency management
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 entryGET /api/knowledge/{source}- Retrieve knowledgePUT /api/knowledge/{source}- Update knowledgeDELETE /api/knowledge/{source}- Delete knowledgeGET /api/knowledge/- List entries usingskip/limitpagination.
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
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
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 twiceThe 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- Code Coverage: unit tests cover the core
active_infer_antspackage, both REST APIs, and the correctness/security fixes (seetests/); 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 lintis green on the maintained surface; the multi-language corpus is outside it (counts indocs/_generated/gate_metrics.md) - Documentation:
./run.sh docsbuilds 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 byscripts/docgen/gate_metrics.py
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- 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
- 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
# 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- Linting: Ruff (lint + format), pinned in the
devextra 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
gnnmarker so./run.sh test-fastneeds 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)
- Fork and Clone: Fork the repository and create a feature branch
- Code Standards: Follow PEP 8 and project-specific guidelines
- Testing: Add comprehensive tests for new features
- Documentation: Update documentation for any new functionality
- Cross-Language Consistency: Ensure implementations work across all supported languages
- Performance: Include performance benchmarks for significant changes
# 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 reportProblem: 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 setupProblem: 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.shProblem: 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.jsonProblem: Memory errors during large simulations
# Reduce simulation parameters
{
"max_iterations": 500, # Reduce from 1000
"memory_limit": "4GB",
"parallel_processes": 2 # Reduce parallelism
}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.shEnable 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- Check Existing Issues: Search GitHub Issues
- Run Diagnostics: Use the built-in status dashboard
- Review Documentation: Check detailed docs
- Community Support: Join our Discord community
We welcome contributions from researchers, developers, and enthusiasts! Here's how to get involved:
- π 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
-
Fork and Clone
git clone https://github.com/your-username/Active_InferAnts.git cd Active_InferAnts git checkout -b feature/your-amazing-feature -
Set Up Development Environment
python3 0_CONTEXT/Computer_Languages/master_controller.py setup ./run.sh setup pre-commit install
-
Make Your Changes
- Follow our coding standards
- Add comprehensive tests
- Update documentation
- Ensure cross-language consistency
-
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
-
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
- 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
Contributors are recognized through:
- Author credits in release notes
- Contributor spotlight in our newsletter
- Exclusive contributor swag
- Speaking opportunities at conferences
- Discussions: Join GitHub Discussions for questions
- Discord: Real-time chat in our Discord community
- Newsletter: Subscribe for updates and research highlights
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
- β 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
When using or sharing this work, you must:
- Credit: Provide attribution to "Active InferAnts" and link to the original repository
- License Notice: Include the license text or a link to the license
- Indicate Changes: Clearly indicate if you made any changes to the material
- Link: Include a URI or hyperlink to the material to the extent reasonably practicable
"Active InferAnts" by Active Inference Institute (@docxology unless otherwise specified) is licensed under CC BY-NC-ND 4.0
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.
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
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
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
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
- π§ Email: blanket@activeinference.institute
- π Issues: GitHub Issues
- π¬ Discussions: GitHub Discussions
- π» Discord: Active Inference Community
- π± Twitter: @ActiveInferAnts
- π¬ Research: Active Inference Institute
| Channel | Purpose |
|---|---|
| π GitHub Issues | Bug reports & technical issues |
| π¬ GitHub Discussions | Questions & community support |
| π» Discord | Real-time chat & community |
| π§ Email | Business & partnership inquiries |
- 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
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
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.