brg_framework 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. brg_framework-0.1.1/.gitignore +6 -0
  2. brg_framework-0.1.1/CHANGELOG.md +18 -0
  3. brg_framework-0.1.1/LICENSE +21 -0
  4. brg_framework-0.1.1/PKG-INFO +187 -0
  5. brg_framework-0.1.1/README.md +148 -0
  6. brg_framework-0.1.1/evals/README.md +38 -0
  7. brg_framework-0.1.1/evals/results/README.md +3 -0
  8. brg_framework-0.1.1/evals/tasks/README.md +17 -0
  9. brg_framework-0.1.1/pyproject.toml +102 -0
  10. brg_framework-0.1.1/server/README.md +108 -0
  11. brg_framework-0.1.1/server/src/brg_mcp/__init__.py +1 -0
  12. brg_framework-0.1.1/server/src/brg_mcp/compas_fd/readme.md +9 -0
  13. brg_framework-0.1.1/server/src/brg_mcp/compas_tna/readme.md +9 -0
  14. brg_framework-0.1.1/server/src/brg_mcp/fd/01_algorithm.md +19 -0
  15. brg_framework-0.1.1/server/src/brg_mcp/fd/02_applications.md +30 -0
  16. brg_framework-0.1.1/server/src/brg_mcp/fd/03_keywords.md +6 -0
  17. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/bundesgartenschau_kassel_1955.png +0 -0
  18. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/cable_net_fabric_formed_thin_shell_buda_texas_2014.png +0 -0
  19. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/convertible_membrane_roofing_metzgergasse_buchs_2014.png +0 -0
  20. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/german_pavilion_world_expo_montreal_1967.png +0 -0
  21. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/munich_ice_ring_roof_1967.png +0 -0
  22. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/navios_corporation_silos_nueva_palmira_1997.png +0 -0
  23. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/paradies_tennis_centre_allschwil_1982.png +0 -0
  24. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/poleni_hooke_arch_and_hanging_chain_analogy_1748.png +0 -0
  25. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/poruklu_marina_arch_supported_membranes_2009.png +0 -0
  26. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/taq_kasra_ctesiphon_arch_iraq_circa_540.png +0 -0
  27. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references/washington_dulles_international_airport_1962.png +0 -0
  28. brg_framework-0.1.1/server/src/brg_mcp/fd/04_references.md +76 -0
  29. brg_framework-0.1.1/server/src/brg_mcp/fd/05_presentations.md +16 -0
  30. brg_framework-0.1.1/server/src/brg_mcp/fd/06_exercises.md +126 -0
  31. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/answers_01_forces.ipynb +287 -0
  32. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/answers_02_force_densities.ipynb +410 -0
  33. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/answers_03_grid_matrices.ipynb +387 -0
  34. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/answers_04_grid_variations.ipynb +489 -0
  35. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/exercise_01_forces.ipynb +199 -0
  36. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/exercise_02_force_densities.ipynb +274 -0
  37. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/exercise_03_grid_matrices.ipynb +249 -0
  38. brg_framework-0.1.1/server/src/brg_mcp/fd/07_exercises/exercise_04_grid_variations.ipynb +277 -0
  39. brg_framework-0.1.1/server/src/brg_mcp/fd/07_extensions.md +24 -0
  40. brg_framework-0.1.1/server/src/brg_mcp/fd/08_style.md +52 -0
  41. brg_framework-0.1.1/server/src/brg_mcp/fd/09_extensions/extension_01_geometric_constraints.ipynb +327 -0
  42. brg_framework-0.1.1/server/src/brg_mcp/fd/09_extensions/extension_02_compression_and_tensegrity.ipynb +327 -0
  43. brg_framework-0.1.1/server/src/brg_mcp/fd/09_extensions/extension_03_minimal_surfaces.ipynb +302 -0
  44. brg_framework-0.1.1/server/src/brg_mcp/fd/09_extensions/extension_04_inflatable_structures.ipynb +325 -0
  45. brg_framework-0.1.1/server/src/brg_mcp/fd/09_extensions/extension_05_differentiable_optimisation.ipynb +314 -0
  46. brg_framework-0.1.1/server/src/brg_mcp/fd/09_extensions/extension_06_inverse_form_finding.ipynb +290 -0
  47. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/01_hypar.md +36 -0
  48. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/02_meshgrid.md +40 -0
  49. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/03_lifted_corner.md +36 -0
  50. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/04_arch_constraint.md +63 -0
  51. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/05_selfweight.md +42 -0
  52. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/06_hypar_membrane.md +69 -0
  53. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/07_conical.md +87 -0
  54. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/08_wave.md +72 -0
  55. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/09_arch_supported.md +89 -0
  56. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/10_catenary_cables.md +87 -0
  57. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/11_corrugated_arch.md +103 -0
  58. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/12_vault_with_lips.md +76 -0
  59. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/13_compressive_arch.md +75 -0
  60. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/14_convertible_wave.md +66 -0
  61. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas/15_curve_constraints.md +158 -0
  62. brg_framework-0.1.1/server/src/brg_mcp/fd/10_compas.md +22 -0
  63. brg_framework-0.1.1/server/src/brg_mcp/fd/readme.md +3 -0
  64. brg_framework-0.1.1/server/src/brg_mcp/server.py +227 -0
  65. brg_framework-0.1.1/server/src/brg_mcp/teaching.py +130 -0
  66. brg_framework-0.1.1/server/src/brg_mcp/tna/01_algorithm.md +39 -0
  67. brg_framework-0.1.1/server/src/brg_mcp/tna/02_applications.md +24 -0
  68. brg_framework-0.1.1/server/src/brg_mcp/tna/03_keywords.md +17 -0
  69. brg_framework-0.1.1/server/src/brg_mcp/tna/04_references.md +17 -0
  70. brg_framework-0.1.1/server/src/brg_mcp/tna/05_presentations.md +18 -0
  71. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/01_tutorial.md +92 -0
  72. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/02_creases.md +100 -0
  73. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/03_holes.md +74 -0
  74. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/04_drop_downs.md +74 -0
  75. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/05_funnel_shell.md +83 -0
  76. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/06_lips.md +151 -0
  77. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/07_fan_vault.md +91 -0
  78. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/08_pillow_vault.md +75 -0
  79. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/09_barrel_vault.md +73 -0
  80. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas/10_cross_vault.md +77 -0
  81. brg_framework-0.1.1/server/src/brg_mcp/tna/06_compas.md +20 -0
  82. brg_framework-0.1.1/server/src/brg_mcp/tna/readme.md +3 -0
  83. brg_framework-0.1.1/server/tests/test_copy_example.py +22 -0
  84. brg_framework-0.1.1/server/tests/test_notebooks.py +35 -0
  85. brg_framework-0.1.1/server/tests/test_server.py +102 -0
  86. brg_framework-0.1.1/server/tests/test_teaching.py +53 -0
  87. brg_framework-0.1.1/skills/brg-methods/SKILL.md +34 -0
  88. brg_framework-0.1.1/skills/brg-methods/scripts/copy_example.py +70 -0
  89. brg_framework-0.1.1/src/brg_framework/__init__.py +12 -0
  90. brg_framework-0.1.1/src/brg_framework/cli.py +98 -0
  91. brg_framework-0.1.1/tests/test_package.py +36 -0
  92. brg_framework-0.1.1/theory/README.md +37 -0
  93. brg_framework-0.1.1/theory/ags/teaching/README.md +12 -0
  94. brg_framework-0.1.1/theory/dem/teaching/README.md +12 -0
  95. brg_framework-0.1.1/theory/dr/teaching/README.md +12 -0
  96. brg_framework-0.1.1/theory/fd/teaching/README.md +12 -0
  97. brg_framework-0.1.1/theory/tna/teaching/README.md +12 -0
  98. brg_framework-0.1.1/theory/tno/teaching/README.md +12 -0
@@ -0,0 +1,6 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ uv.lock
6
+ site/
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.1.1] 2026-11-20
9
+
10
+ ### Added
11
+
12
+ * `brg_framework` package: installs `compas_framework`, then `compas_fd`, `compas_dr`, `compas_tna`, `compas_tno`, `compas_dem`, `compas_ags` and `compas_viewer`.
13
+ * `brg` command: `brg install`, `brg examples`, `brg copy <name>`, `brg version`.
14
+ * The `brg-methods` skill ships inside the package.
15
+
16
+ ### Changed
17
+
18
+ ### Removed
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Block Research Group - ETH Zurich
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.5
2
+ Name: brg_framework
3
+ Version: 0.1.1
4
+ Summary: The Block Research Group packages, with the skill and MCP server for coding agents
5
+ Project-URL: Repository, https://github.com/BlockResearchGroup/brg_framework
6
+ Project-URL: Changelog, https://github.com/BlockResearchGroup/brg_framework/blob/main/CHANGELOG.md
7
+ Project-URL: Issues, https://github.com/BlockResearchGroup/brg_framework/issues
8
+ Author: Block Research Group - ETH Zurich
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Scientific/Engineering
18
+ Requires-Python: >=3.10
19
+ Requires-Dist: compas-ags>=1.3.3
20
+ Requires-Dist: compas-dem>=0.6.0
21
+ Requires-Dist: compas-dr>=0.3.1
22
+ Requires-Dist: compas-fd>=0.5.4
23
+ Requires-Dist: compas-framework>=0.1.3
24
+ Requires-Dist: compas-tna>=0.9.0
25
+ Requires-Dist: compas-tno>=0.4.0
26
+ Requires-Dist: compas-viewer>=2.0.2
27
+ Requires-Dist: compas>=2.16
28
+ Provides-Extra: dev
29
+ Requires-Dist: build; extra == 'dev'
30
+ Requires-Dist: bump-my-version; extra == 'dev'
31
+ Requires-Dist: compas-invocations2; extra == 'dev'
32
+ Requires-Dist: invoke; extra == 'dev'
33
+ Requires-Dist: pytest; extra == 'dev'
34
+ Requires-Dist: ruff; extra == 'dev'
35
+ Provides-Extra: docs
36
+ Requires-Dist: mkdocs; extra == 'docs'
37
+ Requires-Dist: mkdocs-material; extra == 'docs'
38
+ Description-Content-Type: text/markdown
39
+
40
+ # brg_framework
41
+
42
+ Shared knowledge for the Block Research Group packages:
43
+ - [compas_fd](https://github.com/BlockResearchGroup/compas_fd)
44
+ - [compas_dr](https://github.com/BlockResearchGroup/compas_dr)
45
+ - [compas_tna](https://github.com/BlockResearchGroup/compas_tna)
46
+ - [compas_tno](https://github.com/BlockResearchGroup/compas_tno)
47
+ - [compas_dem](https://github.com/BlockResearchGroup/compas_dem)
48
+ - [compas_ags](https://github.com/BlockResearchGroup/compas_ags).
49
+
50
+ LLMs (Claude, Codex, Antigravity, Kimi, Mistral):
51
+ - AGENTS.md - entry point
52
+ - skills - for devs
53
+ - server - for users/students
54
+ - theory - text context about solvers (vector db, rag, links to papers, books)
55
+ - evals - evaluation of the LLM interface
56
+
57
+ ## Install
58
+
59
+ ```bash
60
+ pip install brg_framework
61
+ ```
62
+
63
+ ## Layout of this repository
64
+
65
+ ```text
66
+ brg_framework/
67
+ ├── AGENTS.md # for people and agents editing this repository
68
+ ├── README.md # this file
69
+ ├── pyproject.toml # pip install brg_framework
70
+ ├── CHANGELOG.md
71
+ ├── LICENSE
72
+ ├── src/brg_framework/ # the package: version, list of BRG packages, the brg command
73
+ │ ├── __init__.py
74
+ │ └── cli.py
75
+ ├── tests/ # tests of the package
76
+ ├── .github/workflows/ # build: checks on every push; release: PyPI on a v* tag
77
+ ├── theory/ # one folder per method: fd, dr, tna, tno, dem, ags
78
+ │ └── fd/
79
+ │ ├── index.md # what, when, assumptions, limits
80
+ │ ├── formulation.md # equations with stable ids
81
+ │ ├── glossary.md
82
+ │ ├── references.md
83
+ │ └── teaching/ # exercises, notebooks, slides
84
+ ├── skills/
85
+ │ └── brg-methods/
86
+ │ ├── SKILL.md # which method, which package, where it is
87
+ │ └── scripts/
88
+ │ └── copy_example.py # copies a BRG example as a .py file
89
+ ├── server/ # the MCP server (FastMCP)
90
+ │ ├── INSTALL.md # add the server to each app
91
+ │ ├── pyproject.toml
92
+ │ ├── src/brg_mcp/
93
+ │ │ ├── server.py # every .md page below is one command
94
+ │ │ ├── teaching.py # brg-publish: notebooks to the teaching website
95
+ │ │ ├── fd/ # force density pages and examples
96
+ │ │ ├── tna/ # thrust network analysis pages and examples
97
+ │ │ ├── compas_fd/
98
+ │ │ └── compas_tna/
99
+ │ └── tests/
100
+ └── evals/ # tasks and results, still empty
101
+ ```
102
+
103
+ ## The rules
104
+
105
+ - **Links.** This repository does not describe how to use each package. It only says which package to use and where it is.
106
+ - The `brg-methods` skill picks the package and gives its repository and docs.
107
+ - If the package ships its own skill or `AGENTS.md`, the agent follows it.
108
+ - If not, the agent reads the package itself: README, docs, examples, tests and the docstrings of the installed version.
109
+ - What a package ships is up to its developers.
110
+ - **One source.** Knowledge is Markdown files to be available to chatbots.
111
+ - **The installed package is the API truth.** The agent checks the installed version and reads its docstrings.
112
+ - **One MCP server.** For learners it returns the full BRG text.
113
+ - **Skills follow the [Agent Skills specification](https://agentskills.io/specification).** The `name` is lowercase with hyphens and equals the folder name. The `description` says what it does and when to use it.
114
+ - **Every example in this repository is a real `.py` file that CI runs** against a pinned package version.
115
+
116
+ ## Users
117
+
118
+ | | Learners `skills/` | Coders `server/` |
119
+ | --- | --- | --- |
120
+ | Who | Students and others who want to read theory, see examples and do exercises. They do not write a project | People writing Python with BRG packages |
121
+ | What they ask | "Explain force density." "Show me a hypar example." "Give me exercise 2." | "Form-find this net with compas_fd." "Why does my solver fail?" |
122
+ | Door | The MCP server | The `brg-methods` skill, then the package |
123
+ | Why | Nothing to install. Always the newest text. The full answer appears in the chat, not a link | Works with the installed package version. The agent reads only what it needs |
124
+ | Extras | Links to notebooks on the teaching website | A script that copies examples as files |
125
+
126
+ ## Installation Users - MCP
127
+
128
+ #### Claude
129
+
130
+ - Click your name (bottom left) → Settings → Connectors. On some versions it's the left menu → Plugins.
131
+ - Click Add → Add custom connector.
132
+ - Name: BRG. URL: **https://brg-mcp.fastmcp.app/mcp**. Leave the OAuth fields empty, then click Add.
133
+ - Start a new chat and type mcp_brg.
134
+ - You should see the "BRG methods" menu.
135
+
136
+
137
+ ## Installation Devs - Skills
138
+
139
+
140
+ #### Claude
141
+ ```bash
142
+ npx skills add petrasvestartas/brg_framework -g -y -a claude-code
143
+ ```
144
+
145
+ #### Codex
146
+ ```bash
147
+ npx skills add petrasvestartas/brg_framework -g
148
+ ```
149
+
150
+
151
+
152
+
153
+
154
+
155
+
156
+ ## MCP server
157
+
158
+ - Lives in `server/` in this repository, built with FastMCP.
159
+ - Hosted at one web address. Each student adds it to their own account.
160
+ - Reads the same Markdown files. It holds no content of its own.
161
+ - Returns the full text, and the chat shows it as the answer.
162
+ - No per-package servers.
163
+
164
+ ## Scripts and hooks
165
+
166
+ Goal: copy code as it is, without the model retyping it. A script that copies a file costs almost no tokens and no waiting.
167
+
168
+ **Script (works now).** `skills/brg-methods/scripts/copy_example.py` copies a BRG example into the current folder. Only the Python standard library. It installs with the skill, and the skill tells the agent to run it.
169
+
170
+ ```bash
171
+ python copy_example.py # list the examples
172
+ python copy_example.py tna_cross_vault # write tna_cross_vault.py
173
+ ```
174
+
175
+ **Hooks (planned, not built).** The agent app would run the same script by itself, without a model call. Build them only if the measurements below show they save something.
176
+
177
+ ## Measure first
178
+
179
+ Compare setups on the same tasks: package only, the server, the skill, the skill and the server. Record input, cached and output tokens, model calls, wall time, and pass or fail. Judge correctness first, then tokens, then time. No saving is claimed until these numbers exist.
180
+
181
+ ## References
182
+
183
+ - [Agent Skills specification](https://agentskills.io/specification)
184
+ - [AGENTS.md](https://agents.md/)
185
+ - [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
186
+ - [FastMCP](https://gofastmcp.com/docs/changelog)
187
+ - [AAIF projects](https://aaif.io/projects)
@@ -0,0 +1,148 @@
1
+ # brg_framework
2
+
3
+ Shared knowledge for the Block Research Group packages:
4
+ - [compas_fd](https://github.com/BlockResearchGroup/compas_fd)
5
+ - [compas_dr](https://github.com/BlockResearchGroup/compas_dr)
6
+ - [compas_tna](https://github.com/BlockResearchGroup/compas_tna)
7
+ - [compas_tno](https://github.com/BlockResearchGroup/compas_tno)
8
+ - [compas_dem](https://github.com/BlockResearchGroup/compas_dem)
9
+ - [compas_ags](https://github.com/BlockResearchGroup/compas_ags).
10
+
11
+ LLMs (Claude, Codex, Antigravity, Kimi, Mistral):
12
+ - AGENTS.md - entry point
13
+ - skills - for devs
14
+ - server - for users/students
15
+ - theory - text context about solvers (vector db, rag, links to papers, books)
16
+ - evals - evaluation of the LLM interface
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ pip install brg_framework
22
+ ```
23
+
24
+ ## Layout of this repository
25
+
26
+ ```text
27
+ brg_framework/
28
+ ├── AGENTS.md # for people and agents editing this repository
29
+ ├── README.md # this file
30
+ ├── pyproject.toml # pip install brg_framework
31
+ ├── CHANGELOG.md
32
+ ├── LICENSE
33
+ ├── src/brg_framework/ # the package: version, list of BRG packages, the brg command
34
+ │ ├── __init__.py
35
+ │ └── cli.py
36
+ ├── tests/ # tests of the package
37
+ ├── .github/workflows/ # build: checks on every push; release: PyPI on a v* tag
38
+ ├── theory/ # one folder per method: fd, dr, tna, tno, dem, ags
39
+ │ └── fd/
40
+ │ ├── index.md # what, when, assumptions, limits
41
+ │ ├── formulation.md # equations with stable ids
42
+ │ ├── glossary.md
43
+ │ ├── references.md
44
+ │ └── teaching/ # exercises, notebooks, slides
45
+ ├── skills/
46
+ │ └── brg-methods/
47
+ │ ├── SKILL.md # which method, which package, where it is
48
+ │ └── scripts/
49
+ │ └── copy_example.py # copies a BRG example as a .py file
50
+ ├── server/ # the MCP server (FastMCP)
51
+ │ ├── INSTALL.md # add the server to each app
52
+ │ ├── pyproject.toml
53
+ │ ├── src/brg_mcp/
54
+ │ │ ├── server.py # every .md page below is one command
55
+ │ │ ├── teaching.py # brg-publish: notebooks to the teaching website
56
+ │ │ ├── fd/ # force density pages and examples
57
+ │ │ ├── tna/ # thrust network analysis pages and examples
58
+ │ │ ├── compas_fd/
59
+ │ │ └── compas_tna/
60
+ │ └── tests/
61
+ └── evals/ # tasks and results, still empty
62
+ ```
63
+
64
+ ## The rules
65
+
66
+ - **Links.** This repository does not describe how to use each package. It only says which package to use and where it is.
67
+ - The `brg-methods` skill picks the package and gives its repository and docs.
68
+ - If the package ships its own skill or `AGENTS.md`, the agent follows it.
69
+ - If not, the agent reads the package itself: README, docs, examples, tests and the docstrings of the installed version.
70
+ - What a package ships is up to its developers.
71
+ - **One source.** Knowledge is Markdown files to be available to chatbots.
72
+ - **The installed package is the API truth.** The agent checks the installed version and reads its docstrings.
73
+ - **One MCP server.** For learners it returns the full BRG text.
74
+ - **Skills follow the [Agent Skills specification](https://agentskills.io/specification).** The `name` is lowercase with hyphens and equals the folder name. The `description` says what it does and when to use it.
75
+ - **Every example in this repository is a real `.py` file that CI runs** against a pinned package version.
76
+
77
+ ## Users
78
+
79
+ | | Learners `skills/` | Coders `server/` |
80
+ | --- | --- | --- |
81
+ | Who | Students and others who want to read theory, see examples and do exercises. They do not write a project | People writing Python with BRG packages |
82
+ | What they ask | "Explain force density." "Show me a hypar example." "Give me exercise 2." | "Form-find this net with compas_fd." "Why does my solver fail?" |
83
+ | Door | The MCP server | The `brg-methods` skill, then the package |
84
+ | Why | Nothing to install. Always the newest text. The full answer appears in the chat, not a link | Works with the installed package version. The agent reads only what it needs |
85
+ | Extras | Links to notebooks on the teaching website | A script that copies examples as files |
86
+
87
+ ## Installation Users - MCP
88
+
89
+ #### Claude
90
+
91
+ - Click your name (bottom left) → Settings → Connectors. On some versions it's the left menu → Plugins.
92
+ - Click Add → Add custom connector.
93
+ - Name: BRG. URL: **https://brg-mcp.fastmcp.app/mcp**. Leave the OAuth fields empty, then click Add.
94
+ - Start a new chat and type mcp_brg.
95
+ - You should see the "BRG methods" menu.
96
+
97
+
98
+ ## Installation Devs - Skills
99
+
100
+
101
+ #### Claude
102
+ ```bash
103
+ npx skills add petrasvestartas/brg_framework -g -y -a claude-code
104
+ ```
105
+
106
+ #### Codex
107
+ ```bash
108
+ npx skills add petrasvestartas/brg_framework -g
109
+ ```
110
+
111
+
112
+
113
+
114
+
115
+
116
+
117
+ ## MCP server
118
+
119
+ - Lives in `server/` in this repository, built with FastMCP.
120
+ - Hosted at one web address. Each student adds it to their own account.
121
+ - Reads the same Markdown files. It holds no content of its own.
122
+ - Returns the full text, and the chat shows it as the answer.
123
+ - No per-package servers.
124
+
125
+ ## Scripts and hooks
126
+
127
+ Goal: copy code as it is, without the model retyping it. A script that copies a file costs almost no tokens and no waiting.
128
+
129
+ **Script (works now).** `skills/brg-methods/scripts/copy_example.py` copies a BRG example into the current folder. Only the Python standard library. It installs with the skill, and the skill tells the agent to run it.
130
+
131
+ ```bash
132
+ python copy_example.py # list the examples
133
+ python copy_example.py tna_cross_vault # write tna_cross_vault.py
134
+ ```
135
+
136
+ **Hooks (planned, not built).** The agent app would run the same script by itself, without a model call. Build them only if the measurements below show they save something.
137
+
138
+ ## Measure first
139
+
140
+ Compare setups on the same tasks: package only, the server, the skill, the skill and the server. Record input, cached and output tokens, model calls, wall time, and pass or fail. Judge correctness first, then tokens, then time. No saving is claimed until these numbers exist.
141
+
142
+ ## References
143
+
144
+ - [Agent Skills specification](https://agentskills.io/specification)
145
+ - [AGENTS.md](https://agents.md/)
146
+ - [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
147
+ - [FastMCP](https://gofastmcp.com/docs/changelog)
148
+ - [AAIF projects](https://aaif.io/projects)
@@ -0,0 +1,38 @@
1
+ # Evals
2
+
3
+ Measure before changing the design. Correctness first, then tokens, then time.
4
+
5
+ ## Setups
6
+
7
+ | Id | Setup |
8
+ | --- | --- |
9
+ | A | Package only |
10
+ | B | MCP server as it is |
11
+ | C | MCP server after the fixes |
12
+ | D | Skills only |
13
+ | E | Skills and MCP server |
14
+
15
+ ## Tasks
16
+
17
+ One file per task in `tasks/`. See `tasks/README.md` for the format.
18
+
19
+ | Id | Task | Check |
20
+ | --- | --- | --- |
21
+ | T1 | Hypar: one free node between four supports | Node equals (0.5, 0.5, 0.5) |
22
+ | T2 | Grid net with corner supports and selfweight | Residuals at free nodes below 1e-6 |
23
+ | T3 | Net with sliding supports on curves | Supports lie on their curves |
24
+ | T4 | Thrust network for a vault | Form and force diagrams exist; equilibrium holds |
25
+ | T5 | Explain why the method is linear and when it fails | Rubric of five facts |
26
+ | T6 | Choose the package for a described problem | Matches the table in `skills/brg-methods/SKILL.md` |
27
+ | T7 | A call that changed between two package versions | Passes on the installed version |
28
+ | T8 | Unrelated Python task | Control |
29
+
30
+ ## Record per run
31
+
32
+ Agent app and version, model, setup, task, uncached input tokens, cached input tokens, output tokens, model calls, tool calls, wall time, pass or fail.
33
+
34
+ Run each task at least five times per setup. Put results in `results/` as CSV.
35
+
36
+ ## Runner
37
+
38
+ To be written.
@@ -0,0 +1,3 @@
1
+ # Results
2
+
3
+ One CSV per run date: `2026-11-20.csv`. Columns are listed in `../README.md`.
@@ -0,0 +1,17 @@
1
+ # Tasks
2
+
3
+ One Markdown file per task: `t1_hypar.md`, `t2_selfweight.md`, and so on.
4
+
5
+ ```text
6
+ ---
7
+ id: t1
8
+ packages: [compas_fd]
9
+ check: check_t1.py
10
+ ---
11
+
12
+ The exact prompt given to the agent, word for word.
13
+ ```
14
+
15
+ `check_*.py` runs the code the agent wrote and exits with 0 for pass and 1 for fail.
16
+
17
+ To be written.
@@ -0,0 +1,102 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ # ============================================================================
6
+ # project info
7
+ # ============================================================================
8
+
9
+ [project]
10
+ name = "brg_framework"
11
+ description = "The Block Research Group packages, with the skill and MCP server for coding agents"
12
+ authors = [{ name = "Block Research Group - ETH Zurich" }]
13
+ license = "MIT"
14
+ license-files = ["LICENSE"]
15
+ readme = "README.md"
16
+ requires-python = ">=3.10"
17
+ dynamic = ["version"]
18
+ classifiers = [
19
+ "Development Status :: 3 - Alpha",
20
+ "Topic :: Scientific/Engineering",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ ]
27
+ dependencies = [
28
+ "compas_framework>=0.1.3",
29
+ "compas>=2.16",
30
+ "compas_fd>=0.5.4",
31
+ "compas_dr>=0.3.1",
32
+ "compas_tna>=0.9.0",
33
+ "compas_tno>=0.4.0",
34
+ "compas_dem>=0.6.0",
35
+ "compas_ags>=1.3.3",
36
+ "compas_viewer>=2.0.2",
37
+ ]
38
+
39
+ [project.optional-dependencies]
40
+ dev = ["pytest", "ruff", "invoke", "compas_invocations2", "bump-my-version", "build"]
41
+ docs = ["mkdocs", "mkdocs-material"]
42
+
43
+ [project.scripts]
44
+ brg = "brg_framework.cli:main"
45
+
46
+ [project.urls]
47
+ Repository = "https://github.com/BlockResearchGroup/brg_framework"
48
+ Changelog = "https://github.com/BlockResearchGroup/brg_framework/blob/main/CHANGELOG.md"
49
+ Issues = "https://github.com/BlockResearchGroup/brg_framework/issues"
50
+
51
+ # ============================================================================
52
+ # build: the package, and the skill from skills/ inside it
53
+ # ============================================================================
54
+
55
+ [tool.hatch.version]
56
+ path = "src/brg_framework/__init__.py"
57
+
58
+ [tool.hatch.build.targets.sdist]
59
+ include = ["src", "skills", "tests", "LICENSE", "README.md", "CHANGELOG.md"]
60
+ exclude = ["__pycache__"]
61
+
62
+ [tool.hatch.build.targets.wheel]
63
+ packages = ["src/brg_framework"]
64
+ exclude = ["__pycache__"]
65
+
66
+ [tool.hatch.build.targets.wheel.force-include]
67
+ "skills/brg-methods" = "brg_framework/skills/brg-methods"
68
+
69
+ # ============================================================================
70
+ # checks
71
+ # ============================================================================
72
+
73
+ [tool.pytest.ini_options]
74
+ testpaths = ["tests"]
75
+
76
+ [tool.ruff]
77
+ line-length = 179
78
+ extend-exclude = ["server", "*.ipynb"]
79
+
80
+ [tool.ruff.lint]
81
+ select = ["E", "F", "I"]
82
+ isort = { force-single-line = true }
83
+
84
+ # ============================================================================
85
+ # release: `invoke release patch|minor|major` bumps these, tags and pushes
86
+ # ============================================================================
87
+
88
+ [tool.bumpversion]
89
+ current_version = "0.1.1"
90
+ message = "Bump version to {new_version}"
91
+ commit = true
92
+ tag = true
93
+
94
+ [[tool.bumpversion.files]]
95
+ filename = "src/brg_framework/__init__.py"
96
+ search = "{current_version}"
97
+ replace = "{new_version}"
98
+
99
+ [[tool.bumpversion.files]]
100
+ filename = "CHANGELOG.md"
101
+ search = "Unreleased"
102
+ replace = "[{new_version}] {now:%Y-%m-%d}"
@@ -0,0 +1,108 @@
1
+ # BRG MCP
2
+
3
+ The MCP server of the Block Research Group. A chatbot connects to it and gets short texts on structural design, one command per text. Write "mcp_brg" to know all the functions.
4
+
5
+ ## Layout
6
+
7
+ ```text
8
+ README.md pyproject.toml uv.lock
9
+ src/brg_mcp/server.py the server
10
+ src/brg_mcp/teaching.py copies the notebooks to the teaching website (brg-publish)
11
+ src/brg_mcp/fd/readme.md the command fd (form finding, force density)
12
+ src/brg_mcp/fd/01_algorithm.md the command fd_algorithm (also applications, keywords, references, ...)
13
+ src/brg_mcp/fd/07_exercises/ the notebooks of fd_exercises (08_answers/: of fd_answers)
14
+ src/brg_mcp/tna/ the command tna (thrust network analysis), same layout as fd/
15
+ src/brg_mcp/tna/06_compas/ one page per RhinoVAULT example, each with one standalone Python script (tna_compas_<name>)
16
+ src/brg_mcp/compas_fd/, compas_tna/ the package pages: links to code, documentation and examples
17
+ .github/workflows/teaching.yml publishes the notebooks on every push
18
+ tests/ start the server, check what it offers and what it publishes
19
+ ```
20
+
21
+ ## Connect a chatbot
22
+
23
+ Install [uv](https://docs.astral.sh/uv/) once.
24
+
25
+ ### Directly from GitHub (no clone needed)
26
+
27
+ | Chatbot | Connect |
28
+ |---|---|
29
+ | Claude Code | `claude mcp add --transport stdio --scope user brg -- uvx --from "git+https://github.com/BlockResearchGroup/brg_framework.git#subdirectory=server" brg-mcp` |
30
+ | Codex | `codex mcp add brg -- uvx --from "git+https://github.com/BlockResearchGroup/brg_framework.git#subdirectory=server" brg-mcp` |
31
+ | Antigravity | Add the block below to `~/.gemini/config/mcp_config.json`, restart, and pick **Yes, and always allow** on first run |
32
+ | Cursor, Claude Desktop | Add the block below to your MCP configuration file |
33
+
34
+ ```json
35
+ {
36
+ "mcpServers": {
37
+ "brg": {
38
+ "command": "uvx",
39
+ "args": [
40
+ "--from",
41
+ "git+https://github.com/BlockResearchGroup/brg_framework.git#subdirectory=server",
42
+ "brg-mcp"
43
+ ]
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
49
+ ### From a local clone
50
+
51
+ Replace `/path/to/brg_framework/server` with the path of the cloned `server` folder.
52
+
53
+ | Chatbot | Connect |
54
+ |---|---|
55
+ | Claude Code | `claude mcp add --transport stdio --scope user brg -- uv --directory /path/to/brg_framework/server run brg-mcp` |
56
+ | Codex | `codex mcp add brg -- uv --directory /path/to/brg_framework/server run brg-mcp` |
57
+ | Antigravity | Add the block below to `~/.gemini/config/mcp_config.json`, restart, and pick **Yes, and always allow** on first run |
58
+ | Cursor, Claude Desktop | Add the block below to your MCP configuration file |
59
+
60
+ ```json
61
+ {
62
+ "mcpServers": {
63
+ "brg": {
64
+ "command": "uv",
65
+ "args": ["--directory", "/path/to/brg_framework/server", "run", "brg-mcp"]
66
+ }
67
+ }
68
+ }
69
+ ```
70
+
71
+ Check the connection with `claude mcp list`, `codex mcp list`, or `/mcp` inside Antigravity.
72
+ Restart the chatbot after every change to this folder: it starts the server again and sees the new state.
73
+
74
+ ## Use a command
75
+
76
+ Type the command as a message, in any chatbot: `mcp_brg_fd`. Type `mcp_brg` for the list of all commands. The model calls the server's tool `command` with it
77
+ and repeats the text. Chatbots that show MCP prompts also offer it as a slash command, in their own format
78
+ (Claude Code: `/mcp__brg__fd`).
79
+
80
+ ## Add a command
81
+
82
+ Every file `src/brg_mcp/<folder>/<page>.md` is a command. `readme.md` is the command `<folder>`,
83
+ every other page is `<folder>_<page>`, for example `fd/03_keywords.md` is `fd_keywords`; the number only orders the pages.
84
+ Write in it what the command should answer. The reply of `readme.md` ends with the list of the other pages
85
+ in its folder (`- Keywords: mcp_brg_fd_keywords`), made by the server.
86
+
87
+ ## Notebooks
88
+
89
+ A page with a notebook folder of the same name, numbers aside (`06_exercises.md` and `07_exercises/`), ends with a link
90
+ to each notebook. The link opens the notebook in the Jupyter of the
91
+ [teaching website](https://brg-teaching.github.io/Teaching/CAS/website/library.html#/notebook), in the browser.
92
+
93
+ On every push to `main`, the GitHub Action `.github/workflows/teaching.yml` copies the notebooks to
94
+ `BRG-teaching/Teaching` (`CAS/website/notebooks/<folder>/`, for example `notebooks/fd/`), always overwriting copies of the same name, and the
95
+ teaching website deploys them. The Action needs a deploy key: its public half in `BRG-teaching/Teaching` (Settings, Deploy keys,
96
+ with write access) and its private half as the secret `TEACHING_DEPLOY_KEY` here. By hand: `uv run brg-publish /path/to/Teaching/CAS/website`.
97
+ Restart the chatbot. `server.py` does not change.
98
+
99
+ ## Test
100
+
101
+ The code follows the [COMPAS](https://github.com/compas-dev/compas) style: numpy docstrings, ruff with the same rules.
102
+
103
+ ```bash
104
+ uv sync --extra dev
105
+ uv run ruff check .
106
+ uv run ruff format .
107
+ uv run pytest -q
108
+ ```
@@ -0,0 +1 @@
1
+ """The BRG MCP server."""
@@ -0,0 +1,9 @@
1
+ # COMPAS FD
2
+
3
+ `compas_fd` is the force density package of COMPAS, paired with `compas_viewer` for 3D visualization. Install them with `pip install compas_fd compas_viewer`, or `uv add compas_fd compas_viewer`.
4
+
5
+ - Code: https://github.com/BlockResearchGroup/compas_fd
6
+ - Documentation: https://blockresearchgroup.github.io/compas_fd
7
+ - Examples: https://github.com/BlockResearchGroup/compas_fd/tree/main/docs/examples
8
+ - All fifteen COMPAS Python examples: `mcp_brg_fd_compas`
9
+ - Force density method: `mcp_brg_fd`