FAQ: Getting Started, Architecture, and Module Questions

[web3guru888]

A collection of frequently asked questions about ASI:BUILD. Add your question as a reply and I'll answer it here and update this post.

---

Installation

Q: What Python version does ASI:BUILD require?

A: Python 3.10, 3.11, or 3.12. All three are tested in CI. Python 3.9 is not supported (we use match statements and newer typing features in places).

Q: I just ran pip install -e . and got import errors. What's missing?

A: The base install (pip install -e .) includes only minimal dependencies. Most modules require extras:

pip install -e ".[consciousness]"   # GWT, IIT, synergy
pip install -e ".[graph]"           # Knowledge graphs, Memgraph
pip install -e ".[ml]"              # PyTorch, optimization, deployment
pip install -e ".[quantum]"         # Qiskit
pip install -e ".[crypto]"          # Homomorphic encryption
pip install -e ".[all]"             # Everything (including dev tools)

See pyproject.toml for the full list.

Q: Does ASI:BUILD work on Windows?

A: Partially. The core Python modules work. Some optional dependencies (Memgraph, certain CUDA extensions) are Linux-first. We develop and test on Ubuntu 22.04/24.04 and macOS 14+. Windows support is best-effort.

---

Architecture

Q: What is the Cognitive Blackboard and why does it exist?

A: The Cognitive Blackboard (src/asi_build/integration/blackboard.py) is a typed, thread-safe shared workspace that lets modules exchange data without importing each other directly. It's inspired by the Blackboard Architecture from cognitive science — the same pattern that motivates Global Workspace Theory.

Instead of consciousness importing reasoning directly (tight coupling), both modules post findings to shared topics (consciousness.phi, reasoning.inference) and subscribe to each other's events via the EventBus. This makes it easy to add new modules without modifying existing ones.

See the architecture discussion for a detailed comparison with alternatives.

Q: How many modules currently have Blackboard adapters?

A: Four: consciousness, knowledge_graph, cognitive_synergy, and reasoning. The remaining 24 modules can still be used standalone — the integration layer is additive, not required.

Q: What's the difference between integration/ and integrations/?

A: Two different things with similar names (sorry):

• src/asi_build/integration/ — the internal Cognitive Blackboard integration layer (cross-module coordination)
• src/asi_build/integrations/ — external tool adapters (LangChain ↔ Memgraph, MCP server, SQL-to-graph migration agent)

---

Module-specific

Q: The IIT Φ value looks wrong — it's always between 0 and 1, but shouldn't it depend on system size?

A: You're right to be suspicious. The current Φ computation uses entropy difference as a proxy, not the correct TPM-based (Transition Probability Matrix) Φ from Tononi et al. 2014. This is a known issue tracked in #6. A correct implementation is computationally expensive (O(2^n) over all bipartitions), but there are published approximations. Contributions welcome.

Q: Is the homomorphic encryption module production-ready?

A: No. The BGV/BFV/CKKS interfaces are well-designed, but the NTT-based polynomial multiplication has a coefficient mismatch bug (tracked in #8). Don't use it for real privacy-preserving computation yet. The module is useful for understanding FHE concepts and testing integration patterns.

Q: Can I use the knowledge_graph module without Memgraph?

A: Yes. The BiTemporalKnowledgeGraph has an in-memory backend that works without any external database. Memgraph is only needed for the memgraph_toolbox, servers/, and some integrations/ components.

---

Contributing

Q: I'm new to the codebase. What's a good first contribution?

A: Check the good first issue label. Current options:

• #1 — Add tests for cognitive_synergy
• #2 — Document the KG API with examples
• #13 — Add type hints to bio_inspired
• #14 — Create a Blackboard demo example script
• #15 — Write docs/modules/ pages for any module you find interesting

Q: How do I run the tests?

A:

pip install -e ".[dev]"
pytest tests/ -v           # All tests
pytest tests/ -k synergy   # Tests matching "synergy"
pytest tests/ --co         # List tests without running

CI runs on Python 3.10/3.11/3.12. Tests should pass on all three.

Q: How do I add a new module?

A: See CONTRIBUTING.md. The short version:

1. Create src/asi_build/<your_module>/
2. Add __init__.py with public API
3. Add tests in tests/test_<your_module>.py
4. Add optional dependencies to pyproject.toml extras if needed
5. Open a PR describing what the module does and what theory/technique it implements

---

Have a question not answered here? Reply below and I'll add it to this FAQ.