feat: initial tomllm crate — standalone polyglot release

Rust core + WASM + Python (pyo3) bindings for TOML+LLM comment conventions.
CI: crates.io, PyPI (maturin), npm (wasm-pack) publish on main push.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: elasticdotventures

.github/workflows/python-ci.yml

@@ -0,0 +1,44 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --features python --release --out dist
+          manylinux: auto
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels-linux
+          path: dist/
+      - name: Publish to PyPI
+        uses: PyO3/maturin-action@v1
+        with:
+          command: upload
+          args: --non-interactive --skip-existing dist/*
+        env:
+          MATURIN_PYPI_TOKEN: ${{ secrets.MATURIN_PYPI_TOKEN }}

.github/workflows/rust-ci.yml

@@ -0,0 +1,30 @@
+name: Rust CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+      - run: cargo test --all-features
+
+  publish-crate:
+    needs: test
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+      - run: cargo publish --token ${{ secrets.CRATESIO_API_TOKEN }}

.github/workflows/typescript-ci.yml

@@ -0,0 +1,48 @@
+name: TypeScript / WASM CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  wasm-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+          target: wasm32-unknown-unknown
+      - name: Install wasm-pack
+        run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+      - name: Build WASM (bundler)
+        run: wasm-pack build --target bundler --features wasm --out-dir pkg
+      - name: Build WASM (nodejs)
+        run: wasm-pack build --target nodejs --features wasm --out-dir pkg-nodejs
+      - name: Upload WASM artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wasm-pkg
+          path: pkg/
+
+  publish-npm:
+    needs: wasm-build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+      - uses: actions/download-artifact@v4
+        with:
+          name: wasm-pkg
+          path: pkg/
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

.gitignore

@@ -0,0 +1,7 @@
+/target/
+/dist/
+/pkg/
+/pkg-nodejs/
+**/*.rs.bk
+.env
+Cargo.lock

Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+name = "tomllm"
+version = "0.1.0"
+edition = "2024"
+description = "TOML + LLM comment conventions: tribal knowledge in #comments, stripped for data pipelines"
+license = "MIT"
+repository = "https://github.com/PromptExecution/tomllm"
+keywords = ["toml", "llm", "agent", "config", "annotations"]
+categories = ["parsing", "config", "text-processing"]
+readme = "README.md"
+
+[lib]
+name = "tomllm"
+crate-type = ["cdylib", "rlib"]  # cdylib for WASM/Python, rlib for Rust consumers
+
+[features]
+default = []
+# 🤓 wasm: enables wasm-bindgen exports for TypeScript/JS consumers
+wasm = ["wasm-bindgen", "serde-wasm-bindgen"]
+# 🤓 python: pyo3 extension-module bindings (maturin build --features python)
+python = ["pyo3/extension-module"]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+toml = "0.9"
+regex = "1"
+thiserror = "2"
+
+[dependencies.wasm-bindgen]
+version = "0.2"
+optional = true
+
+[dependencies.serde-wasm-bindgen]
+version = "0.6"
+optional = true
+
+[dependencies.pyo3]
+version = "0.23"
+optional = true
+features = ["extension-module"]
+
+[dev-dependencies]
+tempfile = "3"

README.md

@@ -0,0 +1,108 @@
+# tomllm
+
+TOML + LLM comment conventions: tribal knowledge in `#comments`, stripped for data pipelines.
+
+## Overview
+
+`.tomllm` files are **valid TOML** with enriched `#` comment semantics:
+
+- Comments associate with the next key-value pair or section header
+- Special prefixes encode tribal knowledge: `# 🤓`, `# @tribal:`, `# @example:`, `# @requires:`
+- Tail-map block (last ≤10 lines): fast executive agent scanning without full context load
+- Comments are FOR agents reading the **source file** as documentation — strip them for downstream pipelines
+
+## Cognitive Tiers
+
+Each `.tomllm` file MAY declare its required cognitive tier in the tail-map:
+
+| Tier | Models | Tasks |
+|------|--------|-------|
+| `sm0l` | qwen2.5-3B, haiku | classify, route, grep, format |
+| `ch0nky` | qwen3-coder (local) | implement, refactor, debug |
+| `frontier` | claude-opus/sonnet | architecture, security, novel design |
+
+## Example
+
+```toml
+# @tribal: always use uv pip, never pip install directly
+# @example: uv pip install requests
+package_manager = "uv"
+
+# b00t:map v1
+# summary: Python toolchain config
+# tags: python, uv
+# tier: sm0l
+# complexity: 2
+```
+
+## Usage
+
+### Rust
+
+```rust
+use tomllm::TomllmDoc;
+
+let doc = TomllmDoc::parse(input)?;
+let clean_json = doc.strip_for_pipeline(); // stripped TOML as JSON
+let tier = doc.cognitive_tier();           // sm0l / ch0nky / frontier
+let map = doc.map_block;                   // Option<MapBlock>
+```
+
+### Python (maturin)
+
+```python
+from tomllm import TomllmDoc, MapBlock
+
+doc = TomllmDoc.parse(text)
+print(doc.cognitive_tier())   # "sm0l"
+print(doc.strip_for_pipeline())  # JSON string
+
+block = MapBlock.from_text(text)
+if block:
+    print(block.summary, block.tier, block.tags)
+```
+
+### TypeScript / WASM
+
+```typescript
+import init, { TomllmDoc } from '@promptexecution/tomllm';
+
+await init();
+const doc = TomllmDoc.parse(text);
+```
+
+## Install
+
+```bash
+# Rust
+cargo add tomllm
+
+# Python
+pip install tomllm
+
+# npm
+npm install @promptexecution/tomllm
+```
+
+## Tail-map format
+
+```toml
+# b00t:map v1
+# summary: one-line human+LLM description
+# tags: comma, separated, keywords
+# tier: sm0l|ch0nky|frontier
+# cmds: b00t hive activate inference-qwen3, b00t hive status
+# complexity: 1-10
+```
+
+## License
+
+MIT
+
+<!-- b00t:map v1
+summary: tomllm — TOML + LLM comment conventions crate
+tags: toml, llm, agent, config, annotations, wasm, python
+tier: sm0l
+cmds: cargo test, maturin build --features python, wasm-pack build
+complexity: 3
+-->

package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@promptexecution/tomllm",
+  "version": "0.1.0",
+  "description": "TOML + LLM comment conventions: tribal knowledge in #comments, stripped for data pipelines",
+  "main": "pkg/tomllm.js",
+  "types": "pkg/tomllm.d.ts",
+  "files": ["pkg/"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PromptExecution/tomllm"
+  },
+  "scripts": {
+    "build": "wasm-pack build --target bundler --features wasm",
+    "build:nodejs": "wasm-pack build --target nodejs --features wasm"
+  }
+}

pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["maturin>=1.4,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "tomllm"
+requires-python = ">=3.9"
+description = "TOML + LLM comment conventions: tribal knowledge in #comments, stripped for data pipelines"
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python",
+    "Topic :: Software Development :: Libraries",
+]
+
+[tool.maturin]
+features = ["python"]
+module-name = "tomllm"

src/lib.rs

@@ -0,0 +1,74 @@
+//! # tomllm
+//!
+//! TOML + LLM comment conventions.
+//!
+//! `.tomllm` files are **valid TOML** with enriched `#` comment semantics:
+//! - Comments associate with the next key-value pair or section header
+//! - Special prefixes encode tribal knowledge: `# 🤓`, `# @tribal:`, `# @example:`, `# @requires:`
+//! - Tail-map block (last ≤10 lines): fast executive agent scanning without full context load
+//!
+//! ## Design principle
+//! Comments are FOR agents reading the **source file** as documentation.
+//! When passing data VALUES downstream (to pipelines or further LLMs), strip comments
+//! to minimize token usage. The recipient gets clean TOML; the source stays rich.
+//!
+//! ## Cognitive tier
+//! Each `.tomllm` file MAY declare its required cognitive tier in the tail-map:
+//! - `sm0l` — any small model can process this (classify, route, format)
+//! - `ch0nky` — requires code-generation capable model (implement, refactor)
+//! - `frontier` — requires frontier reasoning (architecture, security, compliance)
+//!
+//! ## Example
+//! ```toml
+//! # @tribal: always use uv pip, never pip install directly
+//! # @example: uv pip install requests
+//! package_manager = "uv"
+//!
+//! # b00t:map v1
+//! # summary: Python toolchain config
+//! # tags: python, uv
+//! # tier: sm0l
+//! ```
+
+use std::collections::BTreeMap;
+use thiserror::Error;
+
+#[cfg(feature = "wasm")]
+use wasm_bindgen::prelude::*;
+
+pub mod loader;
+pub mod map_block;
+pub mod parser;
+pub mod registry;
+pub mod stripper;
+
+#[cfg(feature = "python")]
+pub mod python;
+
+pub use loader::{load_any_typed, load_first, load_typed, resolve_path};
+pub use map_block::{CognitiveTier, MapBlock};
+pub use parser::TomllmDoc;
+pub use registry::TomllmRegistry;
+// 🤓 define_typed_registry! is #[macro_export] — already at crate root; no pub use needed
+
+#[cfg(feature = "python")]
+use pyo3::prelude::*;
+
+/// Python module entry point — called by maturin-generated C extension
+#[cfg(feature = "python")]
+#[pymodule]
+fn tomllm_py(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    python::tomllm(m)
+}
+
+#[derive(Debug, Error)]
+pub enum TomllmError {
+    #[error("TOML parse error: {0}")]
+    TomlParse(#[from] toml::de::Error),
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("Map block parse error: {0}")]
+    MapBlock(String),
+}
+
+pub type Result<T> = std::result::Result<T, TomllmError>;