Metadata-Version: 2.5
Name: brg_framework
Version: 0.1.2
Summary: The Block Research Group packages, with the skill and MCP server for coding agents
Project-URL: Repository, https://github.com/BlockResearchGroup/brg_framework
Project-URL: Changelog, https://github.com/BlockResearchGroup/brg_framework/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/BlockResearchGroup/brg_framework/issues
Author: Block Research Group - ETH Zurich
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: compas-ags>=1.3.3
Requires-Dist: compas-dem>=0.6.0
Requires-Dist: compas-dr>=0.3.1
Requires-Dist: compas-fd>=0.5.4
Requires-Dist: compas-framework>=0.1.3
Requires-Dist: compas-tna>=0.9.0
Requires-Dist: compas-tno>=0.4.0
Requires-Dist: compas-viewer>=2.0.2
Requires-Dist: compas>=2.16
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: bump-my-version; extra == 'dev'
Requires-Dist: compas-invocations2; extra == 'dev'
Requires-Dist: invoke; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Description-Content-Type: text/markdown

# brg_framework

Shared knowledge for the Block Research Group packages: 
- [compas_fd](https://github.com/BlockResearchGroup/compas_fd)
- [compas_dr](https://github.com/BlockResearchGroup/compas_dr)
- [compas_tna](https://github.com/BlockResearchGroup/compas_tna)
- [compas_tno](https://github.com/BlockResearchGroup/compas_tno)
- [compas_dem](https://github.com/BlockResearchGroup/compas_dem)
- [compas_ags](https://github.com/BlockResearchGroup/compas_ags).

LLMs (Claude, Codex, Antigravity, Kimi, Mistral):
- AGENTS.md - entry point
- skills - for devs
- server - for users/students
- theory - text context about solvers (vector db, rag, links to papers, books)
- evals - evaluation of the LLM interface

## Install

```bash
pip install brg_framework
```

## Layout of this repository

```text
brg_framework/
├── AGENTS.md                      # for people and agents editing this repository
├── README.md                      # this file
├── pyproject.toml                 # pip install brg_framework
├── CHANGELOG.md
├── LICENSE
├── src/brg_framework/             # the package: version, list of BRG packages, the brg command
│   ├── __init__.py
│   └── cli.py
├── tests/                         # tests of the package
├── .github/workflows/             # build: checks on every push; release: PyPI on a v* tag
├── theory/                        # one folder per method: fd, dr, tna, tno, dem, ags
│   └── fd/
│       ├── index.md               # what, when, assumptions, limits
│       ├── formulation.md         # equations with stable ids
│       ├── glossary.md
│       ├── references.md
│       └── teaching/              # exercises, notebooks, slides
├── skills/
│   └── brg-methods/
│       ├── SKILL.md               # which method, which package, where it is
│       └── scripts/
│           └── copy_example.py    # copies a BRG example as a .py file
├── server/                        # the MCP server (FastMCP)
│   ├── INSTALL.md                 # add the server to each app
│   ├── pyproject.toml
│   ├── src/brg_mcp/
│   │   ├── server.py              # every .md page below is one command
│   │   ├── teaching.py            # brg-publish: notebooks to the teaching website
│   │   ├── fd/                    # force density pages and examples
│   │   ├── tna/                   # thrust network analysis pages and examples
│   │   ├── compas_fd/
│   │   └── compas_tna/
│   └── tests/
└── evals/                         # tasks and results, still empty
```

## The rules

- **Links.** This repository does not describe how to use each package. It only says which package to use and where it is.
    - The `brg-methods` skill picks the package and gives its repository and docs.
    - If the package ships its own skill or `AGENTS.md`, the agent follows it.
    - If not, the agent reads the package itself: README, docs, examples, tests and the docstrings of the installed version.
    - What a package ships is up to its developers.
- **One source.** Knowledge is Markdown files to be available to chatbots.
- **The installed package is the API truth.** The agent checks the installed version and reads its docstrings.
- **One MCP server.** For learners it returns the full BRG text.
- **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.
- **Every example in this repository is a real `.py` file that CI runs** against a pinned package version.

## Users

| | Learners `skills/` | Coders `server/` |
| --- | --- | --- |
| 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 |
| 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?" |
| Door | The MCP server | The `brg-methods` skill, then the package |
| 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 |
| Extras | Links to notebooks on the teaching website | A script that copies examples as files |

## Installation Users - MCP

#### Claude

- Click your name (bottom left) → Settings → Connectors. On some versions it's the left menu → Plugins.
- Click Add → Add custom connector.
- Name: BRG. URL: **https://brg-mcp.fastmcp.app/mcp**. Leave the OAuth fields empty, then click Add.
- Start a new chat and type mcp_brg.
- You should see the "BRG methods" menu.


## Installation Devs - Skills


#### Claude
```bash
npx skills add petrasvestartas/brg_framework -g -y -a claude-code
```

#### Codex
```bash
npx skills add petrasvestartas/brg_framework -g
```







## MCP server

- Lives in `server/` in this repository, built with FastMCP.
- Hosted at one web address. Each student adds it to their own account.
- Reads the same Markdown files. It holds no content of its own.
- Returns the full text, and the chat shows it as the answer.
- No per-package servers.

## Scripts and hooks

Goal: copy code as it is, without the model retyping it. A script that copies a file costs almost no tokens and no waiting.

**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.

```bash
python copy_example.py                    # list the examples
python copy_example.py tna_cross_vault    # write tna_cross_vault.py
```

**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.

## Measure first

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.

## References

- [Agent Skills specification](https://agentskills.io/specification)
- [AGENTS.md](https://agents.md/)
- [MCP 2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28/)
- [FastMCP](https://gofastmcp.com/docs/changelog)
- [AAIF projects](https://aaif.io/projects)
