Cognitive Robot Abstract Machine (CRAM)

Monorepo for the CRAM cognitive architecture.

Installation

Clone the repo and its submodules

Pull the submodules:

git clone https://github.com/cram2/cognitive_robot_abstract_machine.git
cd cognitive_robot_abstract_machine
git submodule update --init --recursive

CRAM Architecture Installation

To install the CRAM architecture, follow these steps:

Setup the Python venvironment:

sudo apt install -y virtualenv virtualenvwrapper && \
grep -qxF 'export WORKON_HOME=$HOME/.virtualenvs' ~/.bashrc || echo 'export WORKON_HOME=$HOME/.virtualenvs' >> ~/.bashrc && \
grep -qxF 'export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3' ~/.bashrc || echo 'export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3' >> ~/.bashrc && \
grep -qxF 'source /usr/share/virtualenvwrapper/virtualenvwrapper.sh' ~/.bashrc || echo 'source /usr/share/virtualenvwrapper/virtualenvwrapper.sh' >> ~/.bashrc && \
source ~/.bashrc && \
mkvirtualenv cram-env --system-site-packages

Activate / deactivate

workon cram-env
deactivate

Optional: Setup your ROS Workspace

To run the tests or use CRAM with a real robot you need to setup a ROS workspace with the dependencies. The monorepo provides a shell script to setup the workspace for you.

export OVERLAY_WS=$HOME/ros_ws
./scripts/setup_ros_workspace.sh

This will create a ROS workspace in the folder specified in OVERLAY_WS

Install additional dependencies

You need to install the following system dependencies:

sudo apt install -y graphviz graphviz-dev

Install using UV

To install the whole repo we use uv (https://github.com/astral-sh/uv), first to install uv:

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

then install packages:

uv sync --active

If you also want the development dependencies, run:

uv sync --extra dev --active 

semantic_digital_twin's Drake-based IRIS/GCS features (and their tests, test/semantic_digital_twin_test/test_worlds/test_gcs_polygons.py) need the optional iris extra on top of that - it is layered on separately since Drake is a large, semantic_digital_twin-specific dependency:

uv sync --package semantic_digital_twin --extra iris --active --inexact

Running the test suite does not require any dataset-loading dependencies (Drake, py7zr, usd-core/pxr) - tests that need one of these skip cleanly when it is not installed. To actually load GraspClutter6D or ArtVIP datasets (or run their tests against the real packages), add the datasets extra the same way:

uv sync --package semantic_digital_twin --extra datasets --active --inexact

Alternative: Poetry

Alternatively you can use poetry to install all packages in the repository.

Install poetry if you haven't already:

pip install poetry

Install the CRAM package along with its dependencies:

poetry install

Browser visualization

CRAMERA provides live 3D visualization, recorded playback, EQL questions and plan/statechart inspection in the browser. It lives in its own repository, whose scripts/install_stack.py installs it together with this workspace; with it installed, start cramera from the activated environment, then add a LiveVisualization to the executor of the demo you want to follow.

To run tests

1. Install system dependencies, set up and build the ROS 2 workspace

sudo bash .github/docker/setup_ros_workspace.sh && source ~/.bashrc

2. Run a test

pytest test/<package>_test

e.g. pytest test/coraplex_test

Developer / Agent Tooling

.claude/ holds configuration for AI coding agents (Claude Code) working in this repository.

• .claude/skills/local-code-review/ - reviews the current branch against upstream main for bugs and AGENTS.md adherence, then hands back an approval-gated plan to fix every finding (including adding missing tests) before you push.

Contribution

Before committing any changes, please navigate into the project root and install pre-commit hooks:

sudo apt install pre-commit
pre-commit install

Code of Conduct

Any code added to the repository must have at least an 85% test coverage.

🚀 How to Create a Pull Request (PR) in Our System

This guide outlines the best practices for creating a Pull Request in our system to ensure high-quality, maintainable, and robust code.

1. 🤖 AI Code Review First (Pre-PR Check)

   Before submitting your PR, let AI review your code to catch common issues and suggest improvements.

   • GitHub Copilot Reviewer: You can integrate GitHub Copilot as a reviewer directly into your PR process.

   • PyCharm Integration: Alternatively, use AI features directly within PyCharm for an immediate local review.

2. 🛡️ Embrace Test-Driven Thinking

   Our process is Test-Driven Development (TDD):

   • Bug Fixes: If you find a bug, your first step is to write a test that fails (reproduces the bug). Push this failing test, then implement the fix, and ensure the test now passes.

   • The Beyoncé Rule: "If you like it, you should put a test on it." Every new feature or piece of logic needs corresponding tests.

3. 🎯 Focus on Method Quality and Complexity

   • Method Length/Complexity: Keep your methods concise and focused. If the cyclomatic complexity (which you can check using plugins like Code Complexity for JetBrains) reaches the hundreds, your method is highly likely to need refactoring/improvement.

   • Helper Methods: Extract duplicate code into helper methods to adhere to the Don't Repeat Yourself (DRY) principle.

   • Modularity/Plugin Thinking: Think modularly. Code should be designed with a plugin-like approach, making components easily interchangeable or extendable.

   • Side Effects & Entanglement: Methods should be decoupled (not entangled) and should not have hidden side effects. They should ideally do one thing and do it well, following the Single Responsibility Principle (SRP) from SOLID. Example:

     counter = 0      # outer scope state
     
     def increment_counter():
         global counter
         counter += 1   # side effect: modifies outer scope state
         print(f"Counter is now {counter}")  # side effect: I/O
     

4. 📐 Adhere to Code Style and Principles

   • Code Formatting: We use ruff, which is fully PEP 8 compliant, followed by docformatter for docstrings. The krrood-format pre-commit hook formats every modified file before submission.

   • SOLID Principles: Read and understand the SOLID principles for writing robust, maintainable, and scalable software. This article is a great resource: https://realpython.com/solid-principles-python/

5. ✍️ Naming, Typing, and Imports

PR Checklist Summary

[ ] AI (Copilot/PyCharm) has reviewed the code.

[ ] The pre-commit hooks have formatted the code (PEP 8 compliant).

[ ] New features/logic have tests (Beyoncé Rule).

[ ] Bug fixes include a test that reproduced the bug.

[ ] Methods are concise and low in complexity.

[ ] Descriptive names and correct type hints are used.

[ ] Relative importing is used correctly.

[ ] Non-trivial code is documented concisely.

[ ] Code is modular, decoupled, and adheres to SOLID principles.

[ ] Final personal human review complete.