tessellum 0.0.1__tar.gz

tessellum-0.0.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

tessellum-0.0.1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to Tessellum are documented here. The format is loosely [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned for v0.1.0 — Public Beta
+
+- Engine port from parent project (composer + retrieval primitives + format validators)
+- 20 essential skills (capture / search / answer / trail management / maintenance)
+- 8 BB-type example notes (one per Building Block)
+- Conceptual primer term notes (Z + PARA + BB + Epistemic Function + DKS + CQRS)
+- Public-facing how-to library (getting-started, note-format, agent-integration, growing a trail)
+- MCP server exposing v0.1 skills as tools
+- CI workflow (ruff + pytest + format/link validators)
+- `tessellum init` CLI for vault scaffolding
+
+## [0.0.1] — 2026-05-09
+
+### Added — Namespace Reservation
+
+- Repository skeleton with target layout (no `src/` dumping ground; clean separation of code / vault / inbox / data / experiments / scripts / tests)
+- `pyproject.toml` declaring the `tessellum` PyPI package with dependencies for the v0.1 engine port
+- Top-level `src/tessellum/__init__.py` documenting the six-pillar thesis
+- `src/tessellum/format/building_blocks.py` — typed Python registry of the 8 BB types, 4 epistemic layers, and 10 directed edges; the load-bearing primitive of the typed substrate
+- `vault/0_entry_points/entry_master_toc.md` — Master TOC entry for the dogfooded vault
+- `vault/resources/term_dictionary/term_building_block.md` — first conceptual primer term note
+- README + LICENSE (MIT) + CONTRIBUTING + DEVELOPING + this CHANGELOG
+- `.gitignore` for derived artifacts (`data/`, `experiments/`, build outputs)
+
+### Architecture decision
+
+Tessellum dogfoods itself: the project's public documentation lives in `vault/` as typed atomic notes, not in a separate `docs/` directory. See [DEVELOPING.md § Layout Convention](DEVELOPING.md#layout-convention).
+
+[Unreleased]: https://github.com/TianpeiLuke/Tessellum/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/TianpeiLuke/Tessellum/releases/tag/v0.0.1

tessellum-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to Tessellum
+
+Thank you for considering a contribution. Tessellum is in early alpha (v0.0.1) and the contribution surfaces are deliberately limited until v0.1 ships. Read this guide before opening a PR.
+
+## Quick Decision Tree
+
+| What are you contributing? | Where it goes |
+|---|---|
+| New skill (capture / digest / analyze) | Canonical body in `vault/resources/skills/`; thin headers in `.claude/skills/` + `.kiro/skills/`; pipeline sidecar in `vault/resources/skills/skill_<name>.pipeline.yaml` if applicable |
+| New BB sub-kind (e.g., `note_second_category=spreadsheet`) | Term note in `vault/resources/term_dictionary/`; do NOT add a new top-level BB type without a design discussion |
+| New retrieval strategy | Module in `src/tessellum/retrieval/`; add a smoke test in `tests/retrieval/`; update `docs/architecture.md` |
+| New documentation | `vault/` (Tessellum dogfoods itself — there is no separate `docs/`). Pick the right BB-typed location: `term_dictionary/` for definitions, `how_to/` for procedures, `analysis_thoughts/` for arguments + trails, `0_entry_points/` for navigation indexes. |
+| Bug fix | Open an issue first describing the bug; reference it in the PR |
+| Architecture proposal | Open an RFC issue; draft a Folgezettel trail in `vault/resources/analysis_thoughts/` if accepted |
+
+## Layout Convention
+
+Every artifact has a single home. Don't mix.
+
+| Artifact | Location |
+|---|---|
+| `import`-able Python | `src/tessellum/` |
+| Knowledge vault content (your notes) | `vault/` |
+| User input (PDFs, .eml, papers, plans) | `inbox/` |
+| Generated DBs / indexes | `data/` (gitignored) |
+| Experiment outputs | `experiments/` |
+| Operational scripts | `scripts/` |
+| Tests | `tests/` |
+| Public documentation | `docs/` |
+| Skill thin-header (Claude / Kiro) | `.claude/skills/`, `.kiro/skills/` |
+| Skill canonical body (the actual content) | `vault/resources/skills/` |
+
+See [`DEVELOPING.md`](DEVELOPING.md) for the full layout discussion.
+
+## Note Format Standards
+
+Every typed atomic note ("tessellum") MUST have:
+
+```yaml
+---
+tags:
+  - <category-tag>            # First tag describes the note's role (resource, area, project, archive)
+  - <building-block-tag>      # Second tag describes BB type (concept, procedure, model, argument, ...)
+  - <topic-tag>               # Additional topic tags for retrieval
+keywords:
+  - <key-term-1>
+  - <key-term-2>
+topics:
+  - <topic-1>
+language: markdown
+date of note: YYYY-MM-DD
+status: active
+building_block: <concept|procedure|model|argument|counter_argument|hypothesis|empirical_observation|navigation>
+---
+```
+
+Required H2 sections vary by BB type — see `docs/note-format.md`. The validator runs as a pre-commit hook:
+
+```bash
+python scripts/check_yaml_frontmatter.py --path vault/<your-note>.md
+python scripts/check_note_format.py --path vault/<your-note>.md
+```
+
+## Folgezettel Trail Etiquette
+
+If your contribution introduces a new architectural argument, it deserves a Folgezettel trail. Pattern:
+
+1. Author the **root note** as an `argument` BB in `vault/resources/analysis_thoughts/thought_<your_topic>.md`
+2. Run `tessellum trail next <parent>` to get the next FZ ID (or claim a new root by using a number not yet taken)
+3. Write child notes that elaborate (`<root>a`, `<root>b`, ...), challenge (`<root>1` as `counter_argument`), or absorb into synthesis (`<counter>1` as `argument`)
+4. Update `vault/0_entry_points/entry_folgezettel_trails.md` with a row for the new trail
+
+Trails should encode dialectic descent — argument → counter → response → reframe — not just topical proximity.
+
+## Skill Authoring
+
+Skills live in three places (the in-vault SoT pattern):
+
+1. **Canonical body**: `vault/resources/skills/skill_<name>.md` — the actual procedure
+2. **Claude thin header**: `.claude/skills/<name>/SKILL.md` — points at the canonical body
+3. **Kiro thin header**: `.kiro/skills/<name>/SKILL.md` — same pattern
+4. **Pipeline sidecar** (if the skill has typed-contract steps): `vault/resources/skills/skill_<name>.pipeline.yaml`
+
+The thin headers ensure both ecosystems (Claude Code, Kiro CLI) can discover the skill without duplicating the body. See an existing skill for reference.
+
+## Testing
+
+Run the full test suite:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Add tests under `tests/` mirroring the source structure (`tests/composer/`, `tests/retrieval/`, etc.). Smoke tests for end-to-end flows live in `tests/smoke/`.
+
+## Code Style
+
+- Python 3.11+
+- `ruff` for formatting and linting (config in `pyproject.toml`)
+- `mypy` for type checking (gradual; not strict)
+- Imperative commit messages: `add: skill_capture_essay_note` / `fix: rrf merge bug` / `docs: clarify BB ontology`
+
+## Pull Request Process
+
+1. Open an issue describing what you're proposing (unless it's a trivial bug fix)
+2. Branch from `main`: `git checkout -b feature/your-thing`
+3. Write tests
+4. Make sure `pytest` and `ruff check src/` both pass
+5. Open the PR with a clear description; reference the issue
+6. Maintainer review — typically within a week
+
+## Code of Conduct
+
+Be kind, be precise, attack the argument not the person. Tessellum is a system that takes counter-arguments seriously; the project's culture should mirror that.
+
+## License
+
+By contributing, you agree your contributions are licensed under the [MIT License](LICENSE).

tessellum-0.0.1/DEVELOPING.md

@@ -0,0 +1,127 @@
+# Developing Tessellum
+
+Developer-facing guide for working on Tessellum itself (not for users of Tessellum). For user docs, browse `vault/0_entry_points/entry_master_toc.md`.
+
+## Layout Convention
+
+Tessellum **dogfoods itself** — its public documentation lives in `vault/` as typed atomic notes following the same Building Block format the system asks of users. There is no separate `docs/` directory.
+
+| Artifact | Location | Reason |
+|---|---|---|
+| `import`-able Python | `src/tessellum/` | PEP src-layout — installed package surface |
+| Knowledge content (incl. Tessellum's own docs) | `vault/` | Single SoT for typed knowledge; self-applied retrieval |
+| Skill canonical bodies | `vault/resources/skills/` | In-vault skill SoT pattern (FZ 12) |
+| Skill thin-headers | `.claude/skills/`, `.kiro/skills/` | Per-ecosystem entry; both point at the canonical body |
+| User input (PDFs, papers, plans) | `inbox/` | User-facing drop zone |
+| Generated DBs / indexes | `data/` | Regenerable; gitignored |
+| Experiment outputs | `experiments/` | Per-run subdirs |
+| Operational scripts | `scripts/` | Build / update / format utilities |
+| Tests | `tests/` | Mirrors `src/tessellum/` structure |
+| Repo-meta files | repo root | `README.md`, `CHANGELOG.md`, `LICENSE`, `CONTRIBUTING.md`, `DEVELOPING.md`, `pyproject.toml`, `.gitignore`, `.github/` |
+
+**Decision rule for new files**: if it would be useful to *anyone using Tessellum*, it goes in `vault/` as a typed atomic note. If it's only useful to *people working on Tessellum's code*, it goes at repo root or in `scripts/`.
+
+## Why dogfooding?
+
+Three reasons:
+
+1. **Self-applied retrieval** — `tessellum search "BB ontology"` finds the public-facing explanation. Users can grep the system's own docs from day one.
+2. **Format conformance** — Tessellum's own documentation has to follow the format Tessellum demands of its users. If we can't make our docs fit, we're asking users to do something we won't do ourselves.
+3. **Demonstrates the system on itself** — a new user opens the repo, browses `vault/`, and sees a working example of the system documenting itself. That's the strongest README possible.
+
+This decision is documented in [`vault/resources/analysis_thoughts/thought_dogfooding_decision.md`](vault/resources/analysis_thoughts/thought_dogfooding_decision.md) (planned for v0.1).
+
+## Path Resolution
+
+All paths flow through `scripts/config.py` (single SoT). The constants:
+
+```python
+REPO_ROOT      = Path(__file__).resolve().parent.parent
+PACKAGE_DIR    = REPO_ROOT / "src" / "tessellum"
+VAULT_PATH     = REPO_ROOT / "vault"
+INBOX_PATH     = REPO_ROOT / "inbox"
+DATA_PATH      = REPO_ROOT / "data"
+DB_PATH        = DATA_PATH / "databases" / "tessellum_unified.db"
+EXPERIMENTS_PATH = REPO_ROOT / "experiments"
+```
+
+Skills and scripts MUST import from `config.py`. Never hardcode a path.
+
+## Dev Setup
+
+```bash
+# Clone
+git clone https://github.com/TianpeiLuke/Tessellum.git
+cd Tessellum
+
+# Install in editable mode with dev extras
+pip install -e ".[dev]"
+
+# Run the test suite
+pytest
+
+# Lint + format
+ruff check src/
+ruff format src/
+
+# Type check (gradual; not strict)
+mypy src/tessellum/
+```
+
+## Adding a Skill
+
+Skills live in **three** files (the in-vault SoT pattern):
+
+1. **Canonical body**: `vault/resources/skills/skill_<name>.md` — the actual procedure (YAML frontmatter + steps + format spec)
+2. **Claude thin-header**: `.claude/skills/<name>/SKILL.md` — short pointer to the canonical body
+3. **Kiro thin-header**: `.kiro/skills/<name>/SKILL.md` — same pattern
+4. **Pipeline sidecar** (optional): `vault/resources/skills/skill_<name>.pipeline.yaml` — only if the skill has typed-contract steps
+
+## Adding a Building Block sub-kind
+
+The 8 top-level BB types are **closed**. Sub-kinds (`note_second_category:`) are **open** — extend as your domain requires. Procedure:
+
+1. Add the sub-kind value to your note's YAML frontmatter
+2. Add a term note in `vault/resources/term_dictionary/term_<subkind>.md` documenting it
+3. Run `bash scripts/update_notes_database.sh` to re-index
+
+If a sub-kind is generally useful (not domain-specific), open a PR adding it to `src/tessellum/format/building_blocks.py`'s sub-kind suggestion list (planned in v0.1).
+
+## Adding a Folgezettel trail
+
+If your contribution introduces a new architectural argument, it deserves a Folgezettel trail. Pattern:
+
+1. Author the **root note** as an `argument` BB at `vault/resources/analysis_thoughts/thought_<topic>.md`; set `folgezettel: "<N>"` (next root number) and `fz_parent: null`
+2. Write child notes that elaborate, challenge, or absorb into synthesis
+3. Update `vault/0_entry_points/entry_folgezettel_trails.md` with the new trail's row + ASCII tree
+
+See [`vault/resources/term_dictionary/term_folgezettel.md`](vault/resources/term_dictionary/term_folgezettel.md) (planned v0.1) for the full convention.
+
+## Release Process
+
+1. Update `CHANGELOG.md` with the release notes
+2. Bump `version` in `pyproject.toml`
+3. Tag the release: `git tag v0.x.y && git push --tags`
+4. Build: `python -m build`
+5. Upload: `twine upload dist/*`
+6. The `.github/workflows/publish.yml` workflow runs the upload automatically on tag push (planned v0.1)
+
+## Code Style
+
+- **Python 3.11+**
+- **Ruff** for formatting and linting (config in `pyproject.toml`)
+- **Mypy** for type checking — gradual, not strict
+- **Imperative commit messages**: `add: skill_capture_essay_note` / `fix: rrf merge bug` / `docs(vault): clarify BB ontology`
+
+## CI
+
+The CI workflow (`.github/workflows/ci.yml`, planned v0.1) runs:
+- `ruff check src/`
+- `ruff format --check src/`
+- `pytest`
+- `python scripts/check_yaml_frontmatter.py --path vault/`
+- `python scripts/check_note_format.py --path vault/`
+
+## License
+
+[MIT](LICENSE).

tessellum-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tianpei Xie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.