brg_framework 0.1.1__py3-none-any.whl

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.
@@ -0,0 +1,12 @@
1
+ """The Block Research Group packages, with the skill and MCP server for coding agents.
2
+
3
+ Installing this package installs compas_fd, compas_dr, compas_tna, compas_tno, compas_dem and compas_ags.
4
+ The command ``brg`` installs the skill and copies examples. Run ``brg --help``.
5
+
6
+ """
7
+
8
+ __version__ = "0.1.1"
9
+
10
+ MCP_URL = "https://brg-mcp.fastmcp.app/mcp"
11
+
12
+ PACKAGES = ["compas_fd", "compas_dr", "compas_tna", "compas_tno", "compas_dem", "compas_ags"]
brg_framework/cli.py ADDED
@@ -0,0 +1,98 @@
1
+ """The command ``brg``.
2
+
3
+ brg install copy the brg-methods skill into Claude Code and the other agents, print the MCP address
4
+ brg examples list the BRG examples
5
+ brg copy tna_cross_vault write tna_cross_vault.py into the current folder
6
+ brg version the versions of brg_framework and the BRG packages
7
+
8
+ """
9
+
10
+ import argparse
11
+ import importlib.metadata
12
+ import importlib.util
13
+ import shutil
14
+ import sys
15
+ from pathlib import Path
16
+
17
+ from brg_framework import MCP_URL
18
+ from brg_framework import PACKAGES
19
+ from brg_framework import __version__
20
+
21
+ HERE = Path(__file__).parent
22
+ SKILL = "brg-methods"
23
+
24
+ # Claude Code reads ~/.claude/skills. Codex, Antigravity, Kimi Code and others read ~/.agents/skills.
25
+ AGENT_FOLDERS = [Path(".claude") / "skills", Path(".agents") / "skills"]
26
+
27
+
28
+ def skill_folder():
29
+ """The skill shipped in the package, or the one in the repository for an editable install."""
30
+ for folder in (HERE / "skills" / SKILL, HERE.parents[1] / "skills" / SKILL):
31
+ if (folder / "SKILL.md").exists():
32
+ return folder
33
+ raise FileNotFoundError("the {} skill is missing from this installation".format(SKILL))
34
+
35
+
36
+ def copy_example():
37
+ """The script of the skill that copies examples. It is written once, in the skill."""
38
+ path = skill_folder() / "scripts" / "copy_example.py"
39
+ spec = importlib.util.spec_from_file_location("brg_copy_example", path)
40
+ module = importlib.util.module_from_spec(spec)
41
+ spec.loader.exec_module(module)
42
+ return module
43
+
44
+
45
+ def install(home):
46
+ """Copy the skill into every agent folder under ``home``. Return the folders written."""
47
+ source = skill_folder()
48
+ written = []
49
+ for folder in AGENT_FOLDERS:
50
+ target = home / folder / SKILL
51
+ if target.exists():
52
+ shutil.rmtree(target)
53
+ shutil.copytree(source, target, ignore=shutil.ignore_patterns("__pycache__"))
54
+ written.append(target)
55
+ return written
56
+
57
+
58
+ def versions():
59
+ lines = ["brg_framework {}".format(__version__)]
60
+ for name in PACKAGES:
61
+ try:
62
+ lines.append("{} {}".format(name, importlib.metadata.version(name)))
63
+ except importlib.metadata.PackageNotFoundError:
64
+ lines.append("{} not installed".format(name))
65
+ return lines
66
+
67
+
68
+ def main(argv=None):
69
+ parser = argparse.ArgumentParser(prog="brg", description="Block Research Group: skill, MCP server and examples for coding agents.")
70
+ parser.add_argument("--version", action="version", version=__version__)
71
+ commands = parser.add_subparsers(dest="command")
72
+ commands.add_parser("install", help="copy the skill into Claude Code and the other agents, print the MCP address")
73
+ commands.add_parser("examples", help="list the BRG examples")
74
+ copy = commands.add_parser("copy", help="write an example as a .py file into the current folder")
75
+ copy.add_argument("name", help="for example tna_cross_vault")
76
+ copy.add_argument("--force", action="store_true", help="overwrite the file if it exists")
77
+ commands.add_parser("version", help="the versions of brg_framework and the BRG packages")
78
+ args = parser.parse_args(argv)
79
+
80
+ if args.command == "install":
81
+ for target in install(Path.home()):
82
+ print("skill: {}".format(target))
83
+ print("MCP server: {}".format(MCP_URL))
84
+ print("Add it to your app once: https://github.com/BlockResearchGroup/brg_framework/blob/main/server/INSTALL.md")
85
+ return 0
86
+ if args.command == "examples":
87
+ return copy_example().main([])
88
+ if args.command == "copy":
89
+ return copy_example().main([args.name] + (["--force"] if args.force else []))
90
+ if args.command == "version":
91
+ print("\n".join(versions()))
92
+ return 0
93
+ parser.print_help()
94
+ return 0
95
+
96
+
97
+ if __name__ == "__main__":
98
+ sys.exit(main())
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: brg-methods
3
+ description: Chooses the right Block Research Group COMPAS package for a structural design task (form finding of nets and membranes, funicular vaults, masonry assessment, discrete element models, graphic statics) and points to its repository and docs. Use when the user describes a structural form finding or masonry problem, names a BRG package, or asks which BRG or COMPAS package to use.
4
+ license: MIT
5
+ ---
6
+
7
+ # Which BRG package
8
+
9
+ Pick the package from the table. Then let the package do the work. Do not solve the problem by hand.
10
+
11
+ | The user wants | Method | Package | Repository | Docs |
12
+ | --- | --- | --- | --- | --- |
13
+ | Shape of a cable net, membrane or hanging network from force densities | Force density | `compas_fd` | https://github.com/BlockResearchGroup/compas_fd | https://blockresearchgroup.github.io/compas_fd |
14
+ | The same with material stiffness, initial lengths or large displacements | Dynamic relaxation | `compas_dr` | https://github.com/BlockResearchGroup/compas_dr | https://blockresearchgroup.github.io/compas_dr |
15
+ | A compression-only vault under vertical loads, with form and force diagrams | Thrust network analysis | `compas_tna` | https://github.com/BlockResearchGroup/compas_tna | https://blockresearchgroup.github.io/compas_tna |
16
+ | Is a masonry vault safe: minimum or maximum thrust, minimum thickness | Thrust network optimisation | `compas_tno` | https://github.com/BlockResearchGroup/compas_tno | https://blockresearchgroup.github.io/compas_tno |
17
+ | A masonry structure as separate blocks with contacts | Discrete element model | `compas_dem` | https://github.com/BlockResearchGroup/compas_dem | https://blockresearchgroup.github.io/compas_dem |
18
+ | Form and force diagrams of a 2D truss or funicular structure, or its load path | Algebraic graph statics | `compas_ags` | https://github.com/BlockResearchGroup/compas_ags | https://blockresearchgroup.github.io/compas_ags/latest |
19
+
20
+ ## Then
21
+
22
+ 1. If two rows fit, ask one short question to choose. If no row fits, say so.
23
+ 2. Check that the package is installed: `python -c "import <package>; print(<package>.__version__)"`.
24
+ If it is missing: `pip install <package>`. If Python or COMPAS itself is missing, follow https://compas.dev first.
25
+ 3. If the package ships its own skill or an `AGENTS.md`, follow it.
26
+ 4. If not, read the package: its README, `docs/examples/`, `tests/`, and `help()` on the installed names. Trust the installed version over anything you remember.
27
+ 5. Use the package's own examples as the starting point.
28
+ 6. For a BRG example (force density or thrust network analysis), copy the file instead of typing it:
29
+ `python <this skill folder>/scripts/copy_example.py` lists the examples,
30
+ `python <this skill folder>/scripts/copy_example.py tna_cross_vault` writes `tna_cross_vault.py` into the current folder.
31
+
32
+ ## Theory
33
+
34
+ Theory, assumptions and limits of each method are in `theory/<method>/` of https://github.com/BlockResearchGroup/brg_framework.
@@ -0,0 +1,70 @@
1
+ """Copy a BRG example script into the current folder, without retyping it.
2
+
3
+ python copy_example.py list the examples
4
+ python copy_example.py tna_cross_vault write tna_cross_vault.py here
5
+
6
+ The examples are the pages ``server/src/brg_mcp/<method>/<nn>_compas/<nn>_<name>.md`` of the BRG framework on GitHub.
7
+ Only the Python standard library is used. Set ``BRG_REPO`` to read another fork, for example ``BlockResearchGroup/brg_framework``.
8
+
9
+ """
10
+
11
+ import json
12
+ import os
13
+ import re
14
+ import sys
15
+ import urllib.request
16
+ from pathlib import Path
17
+
18
+ REPO = os.environ.get("BRG_REPO", "petrasvestartas/brg_framework")
19
+ BRANCH = os.environ.get("BRG_BRANCH", "main")
20
+ PAGE = re.compile(r"^server/src/brg_mcp/([a-z]+)/\d+_compas/\d+_([a-z0-9_]+)\.md$")
21
+ CODE = re.compile(r"```python\n(.*?)```", re.DOTALL)
22
+
23
+
24
+ def get(url):
25
+ request = urllib.request.Request(url, headers={"User-Agent": "brg-copy-example"})
26
+ with urllib.request.urlopen(request, timeout=30) as response:
27
+ return response.read().decode("utf-8")
28
+
29
+
30
+ def name_of(path):
31
+ """``server/src/brg_mcp/tna/06_compas/10_cross_vault.md`` -> ``tna_cross_vault``, or None for other files."""
32
+ match = PAGE.match(path)
33
+ return "{}_{}".format(*match.groups()) if match else None
34
+
35
+
36
+ def code_of(text):
37
+ """The first Python code block of a page."""
38
+ match = CODE.search(text)
39
+ if not match:
40
+ raise ValueError("the page has no Python code block")
41
+ return match.group(1)
42
+
43
+
44
+ def examples():
45
+ """Every example name and the path of its page."""
46
+ tree = json.loads(get("https://api.github.com/repos/{}/git/trees/{}?recursive=1".format(REPO, BRANCH)))["tree"]
47
+ return {name_of(item["path"]): item["path"] for item in tree if name_of(item["path"])}
48
+
49
+
50
+ def main(args):
51
+ pages = examples()
52
+ if not args:
53
+ print("\n".join(sorted(pages)))
54
+ return 0
55
+ name = args[0].removesuffix(".py")
56
+ if name not in pages:
57
+ print("No example {}. Run without a name to list them.".format(name), file=sys.stderr)
58
+ return 1
59
+ target = Path("{}.py".format(name))
60
+ if target.exists() and "--force" not in args:
61
+ print("{} exists. Add --force to overwrite it.".format(target), file=sys.stderr)
62
+ return 1
63
+ text = get("https://raw.githubusercontent.com/{}/{}/{}".format(REPO, BRANCH, pages[name]))
64
+ target.write_text(code_of(text), encoding="utf-8")
65
+ print("wrote {}".format(target.resolve()))
66
+ return 0
67
+
68
+
69
+ if __name__ == "__main__":
70
+ sys.exit(main(sys.argv[1:]))
@@ -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,9 @@
1
+ brg_framework/__init__.py,sha256=NjWPKEWkpbb8UMY8OzAwuinMAYO4J0zABXBSH8Pc_YY,442
2
+ brg_framework/cli.py,sha256=6Slx25uuTSZvrFM4yGogMuO2DHBZgs8uH1IFhgV-ilU,3809
3
+ brg_framework/skills/brg-methods/SKILL.md,sha256=_ve03nYxQlybTis-xI3xBMp_YoivC9jylmKALdbBlo4,2968
4
+ brg_framework/skills/brg-methods/scripts/copy_example.py,sha256=ejtvxxjzP7j2iMv5fb5Ic8SZTJmDcu79wDCzZNtJGGg,2502
5
+ brg_framework-0.1.1.dist-info/METADATA,sha256=_sp01BJ6AVFnAOzW2ghjKq2ftKZ71-unZws8mNLnWC0,8248
6
+ brg_framework-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ brg_framework-0.1.1.dist-info/entry_points.txt,sha256=g_KLBTGF79MH01VoETY0rsUgHDkNaRCO81CJrzdJx-Y,47
8
+ brg_framework-0.1.1.dist-info/licenses/LICENSE,sha256=tNf0F-3UgZANk-KPUGRtXiv8c8A7CXwtl6cSltBtenE,1071
9
+ brg_framework-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ brg = brg_framework.cli:main
@@ -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.