Merge branch 'main' into main

thousandbrainsproject · Jan 9, 2025 · 15e4c4f · 15e4c4f
2 parents f96518c + 381f052
commit 15e4c4f
Show file tree

Hide file tree

Showing 227 changed files with 1,528 additions and 256 deletions.
diff --git a/.github/actions/pin_comment/action.yml b/.github/actions/pin_comment/action.yml
@@ -0,0 +1,83 @@
+name: "Pin Comment"
+description: "Pins a comment by hiding it with HTML comments and a unique ID"
+
+inputs:
+  message:
+    description: "The message to pin"
+    required: true
+  token:
+    description: "GitHub token"
+    required: true
+  issue_number:
+    description: "The issue or PR number"
+    required: true
+  comment_id:
+    description: "Unique identifier for this pinned comment"
+    required: true
+  working_directory:
+    description: "Path to the repository working directory"
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Pin comment
+      shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
+      env:
+        GITHUB_TOKEN: ${{ inputs.token }}
+        MESSAGE: ${{ inputs.message }}
+        ISSUE_NUMBER: ${{ inputs.issue_number }}
+        COMMENT_ID: ${{ inputs.comment_id }}
+        WORKING_DIRECTORY: ${{ inputs.working_directory }}
+      run: |
+        # Change to working directory
+        cd "${WORKING_DIRECTORY}"
+
+        # Create comment with hidden marker and ID
+        COMMENT="<!--pin-comment-marker-${COMMENT_ID}-->
+        ${MESSAGE}"
+
+        # Properly escape the comment for JSON
+        ESCAPED_COMMENT=$(echo "$COMMENT" | jq -R -s '.')
+
+        # Find and delete old comment with same ID using GitHub token
+        echo "Searching for existing pinned comment with ID: ${COMMENT_ID}"
+        response=$(curl -s -w "%{http_code}" -H "Authorization: token ${GITHUB_TOKEN}" \
+          "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${ISSUE_NUMBER}/comments?per_page=100")
+        status_code=${response: -3}
+        comments=${response:0:-3}
+
+        if [ "$status_code" != "200" ]; then
+          echo "Failed to fetch comments. Status code: ${status_code}"
+          exit 1
+        fi
+
+        old_comment_id=$(echo "$comments" | jq -r ".[] | select(.body | startswith(\"<!--pin-comment-marker-${COMMENT_ID}-->\")) | .id")
+
+        # Update old comment if found
+        if [ ! -z "$old_comment_id" ]; then
+          echo "Updating existing comment with ID: ${old_comment_id}"
+          response=$(curl -s -w "%{http_code}" -X PATCH -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"body\":${ESCAPED_COMMENT}}" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/comments/${old_comment_id}")
+          status_code=${response: -3}
+
+          if [ "$status_code" != "200" ]; then
+            echo "Failed to update comment. Status code: ${status_code}"
+            exit 1
+          fi
+        else
+          # Create new pinned comment using GitHub API directly
+          echo "Creating new pinned comment"
+          response=$(curl -s -w "%{http_code}" -X POST -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"body\":${ESCAPED_COMMENT}}" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${ISSUE_NUMBER}/comments")
+          status_code=${response: -3}
+
+          if [ "$status_code" != "201" ]; then
+            echo "Failed to create comment. Status code: ${status_code}"
+            exit 1
+          fi
+        fi
diff --git a/.github/workflows/docs_preview.yml b/.github/workflows/docs_preview.yml
@@ -0,0 +1,117 @@
+name: Docs Preview
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  pull_request_target:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'tools/github_readme_sync/**'
+      - '.github/workflows/docs_preview.yml'
+
+permissions:
+  pull-requests: write
+
+jobs:
+  deploy_docs_preview:
+    name: deploy-docs-preview
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout tbp.monty
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+          path: tbp.monty
+
+      - name: Create initial PR comment
+        uses: ./tbp.monty/.github/actions/pin_comment
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue_number: ${{ github.event.pull_request.number }}
+          comment_id: docs-preview
+          working_directory: tbp.monty
+          message: |
+            📚 **Documentation Preview**
+
+            Building documentation preview... ⏳
+
+            Check the [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for progress.
+      - name: Set up ~/tbp
+        run: |
+          mkdir -p ~/tbp
+          ln -s $GITHUB_WORKSPACE/tbp.monty ~/tbp/tbp.monty
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+      - name: Install miniconda
+        run: |
+          if [ ! -d ~/miniconda ]
+          then
+            wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh
+            bash ~/miniconda.sh -b -p ~/miniconda
+            rm ~/miniconda.sh
+          fi
+          export PATH="$HOME/miniconda/bin:$PATH"
+          conda --version
+      - name: Create conda environment
+        working-directory: tbp.monty
+        run: |
+          export PATH="$HOME/miniconda/bin:$PATH"
+          (conda env list | grep tbp.monty) && conda remove --name tbp.monty --all --yes || true
+          conda env create
+          source activate tbp.monty
+          pip install -e .[dev,github_readme_sync_tool,print_version_tool]
+      - name: Get version and branch
+        working-directory: tbp.monty
+        run: |
+          export PATH="$HOME/miniconda/bin:$PATH"
+          source activate tbp.monty
+          echo "MONTY_VERSION=$(python -m tools.print_version.cli minor)" >> $GITHUB_ENV
+          # Make branch name safe for semver by replacing invalid chars with dash
+          # Remove trailing dash if present
+          echo "BRANCH_NAME=$(echo ${GITHUB_HEAD_REF} | tr -c '[:alnum:]' '-' | sed 's/-*$//')" >> $GITHUB_ENV
+          # Get current date in ISO format
+          echo "MONTY_DATE=$(date -u +'%Y-%m-%d %H:%M UTC')" >> $GITHUB_ENV
+      - name: Deploy docs
+        working-directory: tbp.monty
+        run: |
+          export PATH="$HOME/miniconda/bin:$PATH"
+          source activate tbp.monty
+          export README_API_KEY=${{ secrets.README_API_KEY }}
+          export IMAGE_PATH=${{ vars.IMAGE_PATH }}
+          python -m tools.github_readme_sync.cli upload docs "${MONTY_VERSION}-${BRANCH_NAME}"
+      - name: Update PR comment on success
+        if: success()
+        uses: ./tbp.monty/.github/actions/pin_comment
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue_number: ${{ github.event.pull_request.number }}
+          comment_id: docs-preview
+          working_directory: tbp.monty
+          message: |
+            📚 **Documentation Preview**
+
+            ✅ A preview of the documentation changes in this PR is available for maintainers at:
+            ${{ vars.DOCS_URL_PREFIX }}v${{ env.MONTY_VERSION }}-${{ env.BRANCH_NAME }}
+
+            Last updated: ${{ env.MONTY_DATE }}
+      - name: Update PR comment on failure
+        if: failure()
+        uses: ./tbp.monty/.github/actions/pin_comment
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue_number: ${{ github.event.pull_request.number }}
+          comment_id: docs-preview
+          working_directory: tbp.monty
+          message: |
+            📚 **Documentation Preview**
+
+            ❌ Failed to build documentation preview.
+
+            Check the [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.
diff --git a/LICENSE b/LICENSE
@@ -1,7 +1,20 @@
+Copyright 2025 Thousand Brains Project
 Copyright 2021-2024 Numenta Inc.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -49,19 +49,21 @@ If you want to use this code, contribute to it, ask questions or propose ideas,
 
 [![](docs/figures/overview/discourse_screenshot.png)](https://thousandbrains.discourse.group/)
 
-If you would like to receive updates, follow us on [Bluesky](https://bluesky.social/thousandbrainsproject) or [Twitter](https://x.com/1000brainsproj) or [LinkedIn](https://www.linkedin.com/showcase/thousand-brains-project/).
+If you would like to receive updates, follow us on [Bluesky](https://bsky.app/profile/1000brainsproj.bsky.social) or [Twitter](https://x.com/1000brainsproj) or [LinkedIn](https://www.linkedin.com/company/thousand-brains-project/).
 
-If you have further questions or suggestions for collaborations, don't hesitate to contact us directly at **[email protected]**.
+If you have further questions or suggestions for collaborations, don't hesitate to contact us directly at **[email protected]**.
 
 # Citing the Project
-If you're writing a paper that references the Thousand Brains Project, please cite our overview paper:
+If you're writing a publication that references the Thousand Brains Project, please cite our TBP whitepaper:
 ```
-@misc{TBP_Overview,
-	title = {The Thousand Brains Project},
-	url = {https://www.numenta.com/wp-content/uploads/2024/06/Short_TBP_Overview.pdf},
-	author = {Clay, Viviane and Leadholm, Niels and Hawkins, Jeff},
-	month = jun,
-	year = {2024},
+@misc{thousandbrainsproject2024,
+      title={The Thousand Brains Project: A New Paradigm for Sensorimotor Intelligence},
+      author={Viviane Clay and Niels Leadholm and Jeff Hawkins},
+      year={2024},
+      eprint={2412.18354},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2412.18354},
 }
 ```
 

diff --git a/benchmarks/configs/__init__.py b/benchmarks/configs/__init__.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/configs/follow_ups/__init__.py b/benchmarks/configs/follow_ups/__init__.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/configs/monty_world_experiments.py b/benchmarks/configs/monty_world_experiments.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2023-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/configs/pretraining_experiments.py b/benchmarks/configs/pretraining_experiments.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/configs/ycb_experiments.py b/benchmarks/configs/ycb_experiments.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/make_detailed_follow_up_configs.py b/benchmarks/make_detailed_follow_up_configs.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/results/montymeetsworld.csv b/benchmarks/results/montymeetsworld.csv
@@ -1,7 +1,7 @@
-Experiment,% Correct,% Used MLH,Num Matching Steps,[Rotation Error (radians)],Run Time,Episode Run Time (s)
-randrot_noise_sim_on_scan_monty_world,85.83%,87.50%,437,0.91,1h5m,29s
-world_image_on_scanned_model,66.67%,83.33%,454,2.10,12m,14s
-dark_world_image_on_scanned_model,31.25%,70.83%,435,2.03,11m,13s
-bright_world_image_on_scanned_model,54.17%,87.50%,464,2.15,12m,15s
-hand_intrusion_world_image_on_scanned_model,37.50%,58.33%,366,1.96,8m,9s
-multi_object_world_image_on_scanned_model,37.50%,41.67%,325,1.93,8m,9s
+Experiment,% Correct,% Used MLH,Num Matching Steps,Rotation Error (radians),Run Time,Episode Run Time (s)
+randrot_noise_sim_on_scan_monty_world,80.00%,85.83%,437,0.94,54m,25s
+world_image_on_scanned_model,66.67%,87.50%,453,2.05,16m,19s
+dark_world_image_on_scanned_model,43.75%,77.08%,433,1.87,15m,18s
+bright_world_image_on_scanned_model,47.92%,83.33%,457,2.16,22m,27s
+hand_intrusion_world_image_on_scanned_model,54.17%,47.92%,333,1.79,11m,13s
+multi_object_world_image_on_scanned_model,41.67%,39.58%,298,1.67,10m,12s
diff --git a/benchmarks/results/ycb_10objs.csv b/benchmarks/results/ycb_10objs.csv
@@ -1,13 +1,13 @@
 Experiment,% Correct,% Used MLH,Num Matching Steps,Rotation Error (radians),Run Time,Episode Run Time (s)
-base_config_10distinctobj_dist_agent,98.57%,5.71%,36,0.31,12m,31s
-base_config_10distinctobj_surf_agent,100.00%,0.00%,28,0.17,6m,27s
-randrot_noise_10distinctobj_dist_agent,99.00%,7.00%,51,0.50,10m,56s
-randrot_noise_10distinctobj_dist_on_distm,99.00%,1.00%,35,0.26,7m,48s
-randrot_noise_10distinctobj_surf_agent,100.00%,1.00%,29,0.36,7m,49s
-randrot_10distinctobj_surf_agent,100.00%,0.00%,29,0.37,4m,29s
-randrot_noise_10distinctobj_5lms_dist_agent,100.00%,3.00%,52,0.88,21m,139s
-base_10simobj_surf_agent,95.00%,10.00%,84,0.21,14m,76s
-randrot_noise_10simobj_dist_agent,81.00%,38.00%,193,0.52,26m,206s
-randrot_noise_10simobj_surf_agent,90.00%,35.00%,178,0.45,34m,294s
-randomrot_rawnoise_10distinctobj_surf_agent,65.00%,77.00%,16,1.60,22m,24s
-base_10multi_distinctobj_dist_agent,74.29%,37.14%,27,0.64,1h9m,2s
+base_config_10distinctobj_dist_agent,99.29%,5.00%,34,0.27,6m,20s
+base_config_10distinctobj_surf_agent,100.00%,0.00%,28,0.17,4m,19s
+randrot_noise_10distinctobj_dist_agent,98.00%,6.00%,47,0.45,5m,31s
+randrot_noise_10distinctobj_dist_on_distm,100.00%,2.00%,36,0.26,4m,28s
+randrot_noise_10distinctobj_surf_agent,99.00%,0.00%,28,0.33,4m,27s
+randrot_10distinctobj_surf_agent,100.00%,0.00%,29,0.40,3m,19s
+randrot_noise_10distinctobj_5lms_dist_agent,100.00%,7.00%,52,0.86,18m,86s
+base_10simobj_surf_agent,95.00%,7.86%,70,0.16,8m,41s
+randrot_noise_10simobj_dist_agent,82.00%,40.00%,182,0.61,16m,116s
+randrot_noise_10simobj_surf_agent,90.00%,34.00%,180,0.50,24m,203s
+randomrot_rawnoise_10distinctobj_surf_agent,73.00%,78.00%,15,1.54,11m,12s
+base_10multi_distinctobj_dist_agent,69.29%,47.14%,25,0.82,1h6m,2s
diff --git a/benchmarks/results/ycb_77objs.csv b/benchmarks/results/ycb_77objs.csv
@@ -1,6 +1,6 @@
 Experiment,% Correct,% Used MLH,Num Matching Steps,Rotation Error (radians),Run Time,Episode Run Time (s)
-base_77obj_dist_agent,93.51%,14.29%,90,0.31,1h37m,295s
-base_77obj_surf_agent,98.27%,5.63%,57,0.21,46m,141s
-randrot_noise_77obj_dist_agent,87.01%,28.57%,155,0.64,2h14m,479s
-randrot_noise_77obj_surf_agent,94.93%,19.48%,102,0.62,1h23m,304s
-randrot_noise_77obj_5lms_dist_agent,93.51%,3.90%,71,0.92,54m,1398s
+base_77obj_dist_agent,93.07%,14.72%,86,0.33,1h4m,197s
+base_77obj_surf_agent,98.27%,5.19%,57,0.21,31m,96s
+randrot_noise_77obj_dist_agent,87.01%,29.87%,148,0.69,1h33m,314s
+randrot_noise_77obj_surf_agent,94.81%,19.91%,107,0.61,55m,198s
+randrot_noise_77obj_5lms_dist_agent,84.42%,9.09%,64,1.07,42m,800s
diff --git a/benchmarks/results/ycb_unsupervised.csv b/benchmarks/results/ycb_unsupervised.csv
@@ -1,4 +1,4 @@
 Experiment,%Correct - 1st Epoch,% Correct - >1st Epoch,Mean Objects per Graph,Mean Graphs per Object,Run Time,Episode Run Time (s)
-surf_agent_unsupervised_10distinctobj,80%,92%,1.22,1.1,17m,10s
-surf_agent_unsupervised_10distinctobj_noise,80%,71.11%,1.05,2.22,106m,64s
-surf_agent_unsupervised_10simobj,20%,67.78%,2.63,2.1,32m,19s
+surf_agent_unsupervised_10distinctobj,80.00%,86.67%,1.11,1.11,16m,10s
+surf_agent_unsupervised_10distinctobj_noise,80.00%,67.78%,1.09,2.78,22m,13s
+surf_agent_unsupervised_10simobj,50.00%,76.67%,2.75,2.20,25m,15s
diff --git a/benchmarks/run.py b/benchmarks/run.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/benchmarks/run_parallel.py b/benchmarks/run_parallel.py
@@ -1,3 +1,4 @@
+# Copyright 2025 Thousand Brains Project
 # Copyright 2022-2024 Numenta Inc.
 #
 # Copyright may exist in Contributors' modifications

diff --git a/docs/community/code-of-conduct.md b/docs/community/code-of-conduct.md
@@ -37,7 +37,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 # Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement by emailing [tbp-conduct@numenta.com](mailto:tbp-conduct@numenta.com) All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement by emailing [conduct@thousandbrains.org](mailto:conduct@thousandbrains.org) All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

diff --git a/docs/community/our-licence-and-patent-pledge-explained.md b/docs/community/our-licence-and-patent-pledge-explained.md
@@ -3,7 +3,7 @@ title: Our Licence and Patent Pledge Explained
 ---
 # Overview
 
-One of the goals of the Thousand Brains Project is to create a new form of AI that benefits the world **to the greatest extent possible**. To accomplish this goal of broad adoption, we have chosen a **permissive license** and **non-assertion pledge** that covers our patents. These two actions, we believe, will encourage researchers, universities, the private sector, and industry specialists to help accelerate our community's progress in building impressive new capabilities to serve the world.
+One of the goals of the Thousand Brains Project is to create a new form of AI that benefits the world **to the greatest extent possible**. To accomplish this goal of broad adoption, we have chosen a **permissive license** and Numenta has created a **non-assertion pledge** that covers the patents related to the Thousand Brains Project. These two actions, we believe, will encourage researchers, universities, the private sector, and industry specialists to help accelerate our community's progress in building impressive new capabilities to serve the world.
 
 # 🛡️ License