{"id":21127018,"url":"https://github.com/pyrustic/braq","last_synced_at":"2025-07-08T23:32:44.816Z","repository":{"id":213120908,"uuid":"733114755","full_name":"pyrustic/braq","owner":"pyrustic","description":"Structured text format with sections","archived":false,"fork":false,"pushed_at":"2024-12-10T20:57:53.000Z","size":118,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-23T23:06:11.487Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyrustic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-18T15:41:49.000Z","updated_at":"2024-12-10T20:57:57.000Z","dependencies_parsed_at":"2023-12-18T16:20:29.430Z","dependency_job_id":"61644b09-9048-4bc8-98eb-7ec179a723d5","html_url":"https://github.com/pyrustic/braq","commit_stats":null,"previous_names":["pyrustic/braq"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pyrustic/braq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fbraq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fbraq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fbraq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fbraq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyrustic","download_url":"https://codeload.github.com/pyrustic/braq/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyrustic%2Fbraq/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264365839,"owners_count":23596912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","code-documentation","config","configfile","prompts"],"created_at":"2024-11-20T04:46:16.253Z","updated_at":"2025-07-08T23:32:44.807Z","avatar_url":"https://github.com/pyrustic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI package version](https://img.shields.io/pypi/v/braq)](https://pypi.org/project/braq)\n[![Downloads](https://static.pepy.tech/badge/braq)](https://pepy.tech/project/braq)\n\n\u003c!-- Cover --\u003e\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/pyrustic/misc/master/assets/braq/cover.png\" alt=\"Cover image\" width=\"650\"\u003e\n    \u003cp align=\"center\"\u003e\n    Braq document with 3 sections\n    \u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- Intro Text --\u003e\n# Braq\n\u003cb\u003eSection-based human-readable data format\u003c/b\u003e\n\n\n## Table of contents\n- [Overview](#overview)\n- [Data format specification](#data-format-specification)\n- [Notable use cases](#notable-use-cases)\n    - [Config files](#config-files)\n    - [Source code documentation](#source-code-documentation)\n    - [AI prompts](#ai-prompts)\n- [Section class](#section-class)\n- [Base functions](#base-functions)\n    - [Parse a document](#parse-a-document)\n    - [Parse a document iteratively](#parse-a-document-iteratively)\n    - [Render a document](#render-a-document)\n- [Misc functions](#misc-functions)\n- [Miscellaneous](#miscellaneous)\n- [Testing and contributing](#testing-and-contributing)\n- [Installation](#installation)\n\n\n# Overview\n**Braq** (pronounced `/ˈbɹæk/`) is a human-readable customizable data format whose reference parser is an eponymous lightweight [Python](https://www.python.org/) library available on [PyPI](#installation).\n\nA Braq **document** is made up of **sections**, each defined by a **header** surrounded by square brackets (hence the name Braq) and a **body** which is just lines of text.\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n\n# Data format specification\nHere are the specs and recommended practices for a valid and neat Braq document:\n\n- A Braq document, when not empty, can be divided into sections. \n\n- A **section** is made up of two parts: a **header** and a **body**. \n\n- The header is defined on its own line, surrounded by two single [square brackets](https://en.wikipedia.org/wiki/Bracket) (opening and closing brackets respectively). \n\n- The body is what is between two consecutive headers or between a header and the end of the document.\n\n- A section can be defined multiple times in the same document. In this case, the parser will concatenate its bodies from top to bottom.\n\n- A section with an empty header is called an **unnamed section**. \n\n- It is recommended to define no more than a single occurrence of a section in a document.\n\n- When a document contains a single unnamed section, it is recommended to place this section at the top of the document.\n\n- When an unnamed document starts a document, it is recommended to omit its header.\n\n- A dictionary data structure encoded with the human-readable [Paradict](https://github.com/pyrustic/paradict) data format can be safely embedded into a section. This section should then be referenced as a **dict section**.\n\n- It is recommended to put 1 empty line as spacing between two consecutive sections.\n\n\n**Example:**\n\n```\nThis is the unnamed section\nthat starts this document.\n\n[section 1]\nLorem ipsum dolor sit amet, \nconsectetur adipiscing elit.\n\n[section 2]\n# dictionary data structure encoded with Paradict\nid = 42\nuser = \"alex\" \nbooks = (dict)\n    sci-fi = (list)\n        \"book 1\"\n        \"book 2\"\n    thriller = (set)\n        \"book 3\"\n\n[section 1]\nit is not recommended to multiply the occurrences\nof a section, however the parser will append this \noccurrence of 'section 1' to the previous one.\n```\n\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Notable use cases\nThis section outlines three notable use cases for **Braq**, namely config files, AI prompts, and code documentation.\n\n## Config files\nBeing able to embed a dictionary data structure in a section makes Braq de facto suitable for config files.\n\n**Example of a KvF config file:**\n```\n# This is the unnamed section of 'my_config.kvf' file.\n# This section will serve as HELP text.\n\n[user]\nid = 42\nname = 'alex'\n\n[gui]\ntheme = 'dark'\nwindow-size = '1024x420'\n```\n\n\n\u003e Check out the config file format [KvF](https://github.com/pyrustic/kvf)\n\n\n## Source code documentation\nThe flexibility of Braq gives the possibility to define custom data formats for specific use cases. Source code documentation is one of those use cases that need Braq with a custom format on top of it.\n\nThis is how Braq can be used to document a function:\n\n```python\ndef add(a, b):\n    \"\"\"\n    This function adds together the values of \n    the provided arguments.\n    \n    [params]\n    - a: first integer\n    - b: second integer\n    \n    [returns]\n    Returns the sum of `a` and `b`\n    \"\"\"\n    return a + b\n```\n\n\u003e [MikeDoc](https://github.com/pyrustic/mikedoc) is a docstring format for generating API references. The library uses **Braq** to parse [docstrings](https://en.wikipedia.org/wiki/Docstring).\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n\n## AI prompts\nThe capability to seamlessly interweave human-readable structured data with prose within a single document is a fundamental capability that a language designed to interact with AI must possess.\n\nAdditionally, the fact that Braq natively supports indentation removes the need for input sanitization, thereby eliminating an entire class of injection attacks.\n\n### Specs\nFollowing are specs for building structured AI prompts with Braq:\n\n- A prompt document must start with the **root instructions** defined inside the top unnamed section.\n- The next section that the AI should actively care about, after the top unnamed section, should be explicitly referenced in the root instructions.\n- User input must be programmatically embedded as a text value of a dictionary key inside a section that is not the top unnamed section.\n\nThat's it ! The specification is deliberately short to avoid unnecessary complexity and also to leave room for creativity.\n\n### Example\n\n```\nYou are an AI assistant, your name is Jarvis.\n\nYou will access the websites defined in the WEB section\nto answer the question that will be submitted to you.\nThe question is stored in the 'input' key of the USER \ndict section.\n\nBe kind and consider the conversation history stored\nin the 'data' key of the HISTORY dict section.\n\n[USER]\ntimestamp = 2024-12-25T16:20:59Z\ninput = (raw)\n    Today, I want you to teach me prompt engineering.\n    Please be concise.\n    ---\n\n[WEB]\nhttps://github.com\nhttps://www.xanadu.net\nhttps://www.wikipedia.org\nhttps://news.ycombinator.com\n\n[HISTORY]\n0 = (dict)\n    timestamp = 2024-12-20T13:10:51Z\n    input = (raw)\n        What is the name of the planet\n        closest to the sun ?\n        ---\n    output = (raw)\n        Mercury is the planet closest\n        to the sun !\n        ---\n1 = (dict)\n    timestamp = 2024-12-22T14:15:54Z\n    input = (raw)\n        What is the largest planet in\n        the solar system?\n        ---\n    output = (raw)\n        Jupiter is the largest planet\n        in the solar system !\n        ---\n```\n\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Section class\nThe `Section` class is an abstraction representing a Braq section. It exposes the `header` and `body` properties and renders itself when its `__str__` method is called implicitly.\n\n```python\nimport braq\n\n# create a Section object\nheader, body = \"my header\", (\"line a\", \"line b\")\nsection = braq.Section(header, body)\n\n# test the properties\nassert section.header == \"my header\"\nassert section.body == \"line a\\nline b\"\n\n# test the rendering\nassert str(section) == \"\"\"\\\n[my header]\nline a\nline b\"\"\"\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Base functions\nBase functions allow you to parse and render documents.\n\n## Parse a document\nThe library exposes the `parse` function which takes as input the text stream to be parsed, then returns a **dictionary** whose keys and values are strings representing headers and bodies respectively.\n\n\u003e Sections sharing the same header are concatenated !\n\u003e The header of an unnamed section is an empty string.\n\n```python\nimport braq\n\ntext = \"\"\"\\\nthis is the unnamed section at\nthe top of this document...\n\n[section 1]\nthis is section 1\"\"\"\n\nd = braq.decode(text)\n\n# check headers\nassert tuple(d.keys()) == (\"\", \"section 1\")\n# check the body of 'section 1'\nassert d[\"section 1\"] == \"this is section 1\"\n```\n\n\u003e Check out the API reference for `braq.parse` [here](https://github.com/pyrustic/braq/blob/master/docs/api/modules/braq/__init__/funcs.md#parse).\n\n## Parse a document iteratively\nA document can be parsed line by line as following:\n\n```python\nimport braq\n\ntext = \"\"\"\\\nthis is the unnamed section\n\n[section 1]\nthis is section 1\"\"\"\n\nfor header, body in braq.parse(text):\n  if header:\n    print(\"[\" + header + \"]\")\n  for line in body:\n    print(line)\n```\n\nOutput:\n\n```text\nthis is the unnamed section\n\n[section 1]\nthis is section 1\n```\n\n\n\u003e Check out the API reference for `braq.parse_iter` [here](https://github.com/pyrustic/braq/blob/master/docs/api/modules/braq/__init__/funcs.md#parse_iter).\n\n\n## Render a document\nRendering a document involves transforming Python objects representing sections into Braq text which is a string that can be displayed on the screen or stored in a file.\n\nThe library exposes the `render` function which accepts as input a sequence of sections (either header-body tuples or `Section` objects) and returns a Braq document.\n\n```python\nimport braq\n\n# sections\nsection_1 = braq.Section(\"section 1\", \"line a\\nline b\")\nsection_2 = \"section 2\", \"line c\\nline d\"\nsection_3 = \"section 3\", (\"line e\", \"line f\")\n\n# rendering\nr = braq.render(section_1, section_2, section_3)\n\nprint(r)\n```\n\nOutput:\n\n```text\n[section 1]\nline a\nline b\n\n[section 2]\nline c\nline d\n\n[section 3]\nline e\nline f\n```\n\n\u003e The `render` function also accepts the `spacing` argument which defaults to 1 and represents the number of lines of spacing between two adjacent sections.\n\n\n\u003e Check out the API reference for `braq.render` [here](https://github.com/pyrustic/braq/blob/master/docs/api/modules/braq/__init__/funcs.md#render).\n\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n\n# Misc functions\nThe `is_header` function accepts a line of text as input and then returns a boolean to indicate whether this line is a header or not.\n\n```python\nimport braq\n\nline_1 = \"[my header]\"\nline_2 = \"[this isn't a header] at all\"\nassert braq.is_header(line_1) is True\nassert braq.is_header(line_2) is False\n```\n\nThe `get_header` function accepts a line of text as input and returns a string if the line is a header. Otherwise, `None` is returned.\n\n```python\nimport braq\n\nline_1 = \"[my header]\"\nline_2 = \"[this isn't a header] at all\"\nassert braq.get_header(line_1) == \"my header\"\nassert braq.get_header(line_2) is None\n```\n\n\u003e Check out the API reference for `braq.check_header` and `braq.get_header` [here](https://github.com/pyrustic/braq/blob/master/docs/api/modules/braq/__init__/funcs.md#check_header).\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Miscellaneous\nCollection of miscellaneous notes.\n\n## Cover image\nThe beautiful cover image is generated with [Carbon](https://carbon.now.sh/about).\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Testing and contributing\nFeel free to **open an issue** to report a bug, suggest some changes, show some useful code snippets, or discuss anything related to this project. You can also directly email [me](https://pyrustic.github.io/#contact).\n\n## Setup your development environment\nFollowing are instructions to setup your development environment\n\n```bash\n# create and activate a virtual environment\npython -m venv venv\nsource venv/bin/activate\n\n# clone the project then change into its directory\ngit clone https://github.com/pyrustic/braq.git\ncd braq\n\n# install the package locally (editable mode)\npip install -e .\n\n# run tests\npython -m tests\n\n# deactivate the virtual environment\ndeactivate\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# Installation\n**Braq** is **cross-platform**. It is built on [Ubuntu](https://ubuntu.com/download/desktop) and should work on **Python 3.5** or **newer**.\n\n## Create and activate a virtual environment\n```bash\npython -m venv venv\nsource venv/bin/activate\n```\n\n## Install for the first time\n\n```bash\npip install braq\n```\n\n## Upgrade the package\n```bash\npip install braq --upgrade --upgrade-strategy eager\n```\n\n## Deactivate the virtual environment\n```bash\ndeactivate\n```\n\n\u003cp align=\"right\"\u003e\u003ca href=\"#readme\"\u003eBack to top\u003c/a\u003e\u003c/p\u003e\n\n# About the author\nHello world, I'm Alex, a tech enthusiast ! Feel free to get in touch with [me](https://pyrustic.github.io/#contact) !\n\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n[Back to top](#readme)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrustic%2Fbraq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyrustic%2Fbraq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyrustic%2Fbraq/lists"}