lesson-book 0.1.0__tar.gz

lesson_book-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lesson Book contributors
+
+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.

lesson_book-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: lesson-book
+Version: 0.1.0
+Summary: Tuition memory for traders: a local-first, deterministic mistake ledger with situation matching — before you act, it reminds you where you paid before.
+License-Expression: MIT
+Keywords: trading,journal,mistakes,lessons,discipline,cli,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# lesson-book
+
+**Tuition memory for traders.** A local-first, deterministic mistake ledger:
+record what each mistake cost you, tag it, and `lb match` reminds you of it
+the next time the same situation shows up — **before** you act. Python
+3.11+, **zero dependencies**, Windows / Linux / macOS. No LLM, no cloud, no
+statistics: the reminder is reproducible and auditable.
+
+**Status:** v0.1 — alpha. The matching logic is distilled from a production
+trading system's lesson-matching module; this standalone package is new.
+
+## Why this exists
+
+Your trading system has a memory problem: it forgets. The mistake you paid
+1,200 for last month looks like a fresh opportunity today, because nothing
+stood between the idea and the order. Trading journals solve the *recording*
+half — they are ledgers of what happened. `lesson-book` solves the
+*retrieval* half: it keeps the tuition in a form that can speak up when the
+same situation appears again.
+
+Two design commitments make it different from journaling apps and LLM
+"memory" systems:
+
+1. **Deterministic, not statistical.** Scoring is a fixed weighted formula
+   (code +3, industry +2, market cap +1, volatility proximity bonus, tag
+   overlap bonus). Same situation, same reminder, every time — the opposite
+   of an LLM memory that improvises.
+2. **Local-first and verifiable.** The book is a plain append-only JSONL
+   file in your repo. `git log` on it *is* your audit trail; nothing ever
+   leaves your machine.
+
+## Philosophy
+
+**Tuition is capital — the system does not forget what you paid for, and it
+reminds you before you pay again.**
+
+This is the checklist culture of aviation and medicine, applied to trading:
+Gawande's [*The Checklist Manifesto*](https://en.wikipedia.org/wiki/The_Checklist_Manifesto)
+is the canonical argument that simple checklists reduce catastrophic error
+rates by an order of magnitude. And it is the **premortem** in reverse:
+[Klein (2007), "Performing a Project Premortem"](https://hbr.org/2007/09/performing-a-project-premortem)
+asks you to imagine, before acting, that you already failed and explain why.
+`lb match` is the automated premortem: it surfaces the historical answers to
+"why will this fail?" without you having to ask.
+
+The [IOM (1999), *To Err Is Human*](https://nap.nationalacademies.org/catalog/9728/to-err-is-human-building-a-safer-health-system)
+framing applies directly: errors are a system problem, not a character
+flaw. The book exists to improve the system — classification, review and
+retrieval — never to punish the person. That is why records carry `cost`
+(a number, not a shame) and why the tool classifies but never enforces:
+rules, positions and limits stay with you.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install lesson-book
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m lesson_book --help
+
+python examples/demo.py   # record, match, review on a scratch book
+```
+
+Your own book:
+
+```bash
+# record a mistake — classification happens via the rule table
+lb add --book book.jsonl \
+  --title "bought into the open gap" \
+  --issue execution_failed --error-category price_limit \
+  --date 2026-08-01 --code 600000 --industry banking \
+  --volatility 0.03 --tags gap,limit-up --cost 1200 \
+  --lesson "never chase the open gap; wait for the retest"
+
+# before acting tomorrow: ask the book
+lb match --book book.jsonl --industry banking --volatility 0.03 \
+  --code 600000 --tags gap
+# -> the 2026-08-01 record, score 8.0, lesson: "never chase the open gap..."
+
+# import an existing ##-style markdown knowledge base
+lb import-lessons --from LESSONS.md --book book.jsonl
+
+# daily review of what the day cost
+lb review --book book.jsonl --day 2026-08-01 --out reviews/
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `add` | Record a mistake: `--title`, `--issue` (required), `--error-category`, context fields (`--code`, `--industry`, `--volatility`, `--market-cap`, `--tags`), `--cost`, `--lesson`, `--situation`. Classified via the rule table (P1/P2, fail-closed to P2) |
+| `import-lessons` | Parse a `##`-headed markdown knowledge base with `**Field:**` metadata (Code/Industry/Volatility/Market Cap/Tags/Cost/Lesson/...) into the book. Idempotent by title |
+| `match` | Rank lessons relevant to the current situation; exit 1 when nothing matches (a pre-action hook can fail-closed on it) |
+| `review` | Daily review: cards grouped by category and priority, total cost, markdown output |
+| `version` | Print version |
+
+## The book
+
+`book.jsonl` — append-only, one JSON record per line:
+
+```json
+{"schema_version": "lesson_book.lesson.v1", "record_id": "...",
+ "title": "bought into the open gap", "date": "2026-08-01",
+ "code": "600000", "industry": "banking", "volatility": 0.03,
+ "market_cap": "large", "tags": ["gap", "limit-up"],
+ "category": "price_limit_rejected", "priority": "P1",
+ "cost": 1200.0, "lesson": "never chase the open gap",
+ "situation": "", "recorded_at": "..."}
+```
+
+Matching score (deterministic):
+
+| Signal | Weight |
+| --- | --- |
+| same code | +3.0 |
+| same industry | +2.0 |
+| same market cap | +1.0 |
+| volatility proximity | up to +1.5 (decays 5× the gap) |
+| tag overlap | +0.5 per tag, capped at +1.5 |
+
+A primary match (code / industry / market cap) is required for a non-zero
+score — the book never speaks up about situations it has no grounds to
+compare.
+
+## Classification rules
+
+`add` classifies `issue` + `error_category` through a plain rule table
+(`category`, `priority`, `action`), fully overridable in code. Defaults:
+
+| issue | error_category | category | priority |
+| --- | --- | --- | --- |
+| `execution_without_action_plan` | — | `planning_gap` | P1 |
+| `execution_failed` | `price_limit` | `price_limit_rejected` | P1 |
+| `execution_failed` | `trading_time_closed` | `trading_time_closed` | P1 |
+| `execution_failed` | `receipt_reader_error` | `receipt_reader_error` | P1 |
+| `execution_failed` | — | `execution_failure` | P1 |
+| anything else | — | `unclassified` | P2 |
+
+Unclassified records are P2 with "review manually and extend the rule table"
+— the taxonomy grows with you, never silently.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest
+```
+
+CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11
+and 3.12. Issues are handled on weekends; pull requests are welcome.
+
+## Related work
+
+- [Klein (2007), Performing a Project Premortem (HBR)](https://hbr.org/2007/09/performing-a-project-premortem) — imagine the failure before it happens
+- [Gawande (2009), The Checklist Manifesto](https://en.wikipedia.org/wiki/The_Checklist_Manifesto) — checklists as error-rate reduction
+- [IOM (1999), To Err Is Human](https://nap.nationalacademies.org/catalog/9728/to-err-is-human-building-a-safer-health-system) — errors as system problems
+
+## License
+
+MIT

lesson_book-0.1.0/README.md

@@ -0,0 +1,161 @@
+# lesson-book
+
+**Tuition memory for traders.** A local-first, deterministic mistake ledger:
+record what each mistake cost you, tag it, and `lb match` reminds you of it
+the next time the same situation shows up — **before** you act. Python
+3.11+, **zero dependencies**, Windows / Linux / macOS. No LLM, no cloud, no
+statistics: the reminder is reproducible and auditable.
+
+**Status:** v0.1 — alpha. The matching logic is distilled from a production
+trading system's lesson-matching module; this standalone package is new.
+
+## Why this exists
+
+Your trading system has a memory problem: it forgets. The mistake you paid
+1,200 for last month looks like a fresh opportunity today, because nothing
+stood between the idea and the order. Trading journals solve the *recording*
+half — they are ledgers of what happened. `lesson-book` solves the
+*retrieval* half: it keeps the tuition in a form that can speak up when the
+same situation appears again.
+
+Two design commitments make it different from journaling apps and LLM
+"memory" systems:
+
+1. **Deterministic, not statistical.** Scoring is a fixed weighted formula
+   (code +3, industry +2, market cap +1, volatility proximity bonus, tag
+   overlap bonus). Same situation, same reminder, every time — the opposite
+   of an LLM memory that improvises.
+2. **Local-first and verifiable.** The book is a plain append-only JSONL
+   file in your repo. `git log` on it *is* your audit trail; nothing ever
+   leaves your machine.
+
+## Philosophy
+
+**Tuition is capital — the system does not forget what you paid for, and it
+reminds you before you pay again.**
+
+This is the checklist culture of aviation and medicine, applied to trading:
+Gawande's [*The Checklist Manifesto*](https://en.wikipedia.org/wiki/The_Checklist_Manifesto)
+is the canonical argument that simple checklists reduce catastrophic error
+rates by an order of magnitude. And it is the **premortem** in reverse:
+[Klein (2007), "Performing a Project Premortem"](https://hbr.org/2007/09/performing-a-project-premortem)
+asks you to imagine, before acting, that you already failed and explain why.
+`lb match` is the automated premortem: it surfaces the historical answers to
+"why will this fail?" without you having to ask.
+
+The [IOM (1999), *To Err Is Human*](https://nap.nationalacademies.org/catalog/9728/to-err-is-human-building-a-safer-health-system)
+framing applies directly: errors are a system problem, not a character
+flaw. The book exists to improve the system — classification, review and
+retrieval — never to punish the person. That is why records carry `cost`
+(a number, not a shame) and why the tool classifies but never enforces:
+rules, positions and limits stay with you.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install lesson-book
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m lesson_book --help
+
+python examples/demo.py   # record, match, review on a scratch book
+```
+
+Your own book:
+
+```bash
+# record a mistake — classification happens via the rule table
+lb add --book book.jsonl \
+  --title "bought into the open gap" \
+  --issue execution_failed --error-category price_limit \
+  --date 2026-08-01 --code 600000 --industry banking \
+  --volatility 0.03 --tags gap,limit-up --cost 1200 \
+  --lesson "never chase the open gap; wait for the retest"
+
+# before acting tomorrow: ask the book
+lb match --book book.jsonl --industry banking --volatility 0.03 \
+  --code 600000 --tags gap
+# -> the 2026-08-01 record, score 8.0, lesson: "never chase the open gap..."
+
+# import an existing ##-style markdown knowledge base
+lb import-lessons --from LESSONS.md --book book.jsonl
+
+# daily review of what the day cost
+lb review --book book.jsonl --day 2026-08-01 --out reviews/
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `add` | Record a mistake: `--title`, `--issue` (required), `--error-category`, context fields (`--code`, `--industry`, `--volatility`, `--market-cap`, `--tags`), `--cost`, `--lesson`, `--situation`. Classified via the rule table (P1/P2, fail-closed to P2) |
+| `import-lessons` | Parse a `##`-headed markdown knowledge base with `**Field:**` metadata (Code/Industry/Volatility/Market Cap/Tags/Cost/Lesson/...) into the book. Idempotent by title |
+| `match` | Rank lessons relevant to the current situation; exit 1 when nothing matches (a pre-action hook can fail-closed on it) |
+| `review` | Daily review: cards grouped by category and priority, total cost, markdown output |
+| `version` | Print version |
+
+## The book
+
+`book.jsonl` — append-only, one JSON record per line:
+
+```json
+{"schema_version": "lesson_book.lesson.v1", "record_id": "...",
+ "title": "bought into the open gap", "date": "2026-08-01",
+ "code": "600000", "industry": "banking", "volatility": 0.03,
+ "market_cap": "large", "tags": ["gap", "limit-up"],
+ "category": "price_limit_rejected", "priority": "P1",
+ "cost": 1200.0, "lesson": "never chase the open gap",
+ "situation": "", "recorded_at": "..."}
+```
+
+Matching score (deterministic):
+
+| Signal | Weight |
+| --- | --- |
+| same code | +3.0 |
+| same industry | +2.0 |
+| same market cap | +1.0 |
+| volatility proximity | up to +1.5 (decays 5× the gap) |
+| tag overlap | +0.5 per tag, capped at +1.5 |
+
+A primary match (code / industry / market cap) is required for a non-zero
+score — the book never speaks up about situations it has no grounds to
+compare.
+
+## Classification rules
+
+`add` classifies `issue` + `error_category` through a plain rule table
+(`category`, `priority`, `action`), fully overridable in code. Defaults:
+
+| issue | error_category | category | priority |
+| --- | --- | --- | --- |
+| `execution_without_action_plan` | — | `planning_gap` | P1 |
+| `execution_failed` | `price_limit` | `price_limit_rejected` | P1 |
+| `execution_failed` | `trading_time_closed` | `trading_time_closed` | P1 |
+| `execution_failed` | `receipt_reader_error` | `receipt_reader_error` | P1 |
+| `execution_failed` | — | `execution_failure` | P1 |
+| anything else | — | `unclassified` | P2 |
+
+Unclassified records are P2 with "review manually and extend the rule table"
+— the taxonomy grows with you, never silently.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest
+```
+
+CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11
+and 3.12. Issues are handled on weekends; pull requests are welcome.
+
+## Related work
+
+- [Klein (2007), Performing a Project Premortem (HBR)](https://hbr.org/2007/09/performing-a-project-premortem) — imagine the failure before it happens
+- [Gawande (2009), The Checklist Manifesto](https://en.wikipedia.org/wiki/The_Checklist_Manifesto) — checklists as error-rate reduction
+- [IOM (1999), To Err Is Human](https://nap.nationalacademies.org/catalog/9728/to-err-is-human-building-a-safer-health-system) — errors as system problems
+
+## License
+
+MIT

lesson_book-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lesson-book"
+version = "0.1.0"
+description = "Tuition memory for traders: a local-first, deterministic mistake ledger with situation matching — before you act, it reminds you where you paid before."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["trading", "journal", "mistakes", "lessons", "discipline", "cli", "local-first"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+
+[project.scripts]
+lb = "lesson_book.cli:main"
+lesson-book = "lesson_book.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lesson_book-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lesson_book-0.1.0/src/lesson_book/__init__.py

@@ -0,0 +1,29 @@
+"""Tuition memory: a local-first, deterministic mistake ledger.
+
+Record what each mistake cost you, tag it, and let ``match`` remind you of
+it the next time the same situation shows up — before you act.  No LLM, no
+cloud, no statistics: just an append-only JSONL book and deterministic
+scoring, so the reminder is reproducible and auditable.
+"""
+
+from .lessons import import_lessons_markdown, match_lessons, score_lesson
+from .mistakes import (
+    add_mistake,
+    classify,
+    default_rules,
+    load_book,
+    review_day,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "add_mistake",
+    "classify",
+    "default_rules",
+    "import_lessons_markdown",
+    "load_book",
+    "match_lessons",
+    "review_day",
+    "score_lesson",
+]

lesson_book-0.1.0/src/lesson_book/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lesson_book-0.1.0/src/lesson_book/cli.py

@@ -0,0 +1,136 @@
+"""Command-line interface for lesson-book.
+
+Subcommands:
+
+- ``add``             record a mistake (classified via the rule table)
+- ``import-lessons``  parse a ``##``-style markdown knowledge base into the book
+- ``match``           rank lessons relevant to a current situation (pre-action)
+- ``review``          daily review markdown of one day's mistakes
+- ``version``         print version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from . import __version__
+from .lessons import import_lessons_markdown, match_lessons
+from .mistakes import add_mistake, review_day
+
+
+def _print_json(body: Any) -> None:
+    print(json.dumps(body, ensure_ascii=False, indent=2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lb",
+        description="Tuition memory: a local-first, deterministic mistake ledger.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    add = sub.add_parser("add", help="record a mistake")
+    add.add_argument("--book", required=True, help="JSONL book path")
+    add.add_argument("--title", required=True)
+    add.add_argument("--issue", required=True)
+    add.add_argument("--error-category", default=None)
+    add.add_argument("--date", default=None)
+    add.add_argument("--code", default="")
+    add.add_argument("--industry", default="")
+    add.add_argument("--volatility", type=float, default=None)
+    add.add_argument("--market-cap", default="")
+    add.add_argument("--tags", default="", help="comma-separated tags")
+    add.add_argument("--cost", type=float, default=None)
+    add.add_argument("--lesson", default="")
+    add.add_argument("--situation", default="")
+
+    imp = sub.add_parser("import-lessons", help="import a markdown knowledge base")
+    imp.add_argument("--from", dest="from_path", required=True, help="markdown lessons file")
+    imp.add_argument("--book", required=True, help="JSONL book path")
+
+    match = sub.add_parser("match", help="match the current situation against the book")
+    match.add_argument("--book", required=True)
+    match.add_argument("--code", default="")
+    match.add_argument("--industry", required=True)
+    match.add_argument("--volatility", type=float, required=True)
+    match.add_argument("--market-cap", default="")
+    match.add_argument("--tags", default="", help="comma-separated tags")
+    match.add_argument("--top-n", type=int, default=3)
+    match.add_argument("--days-window", type=int, default=None)
+
+    review = sub.add_parser("review", help="daily review of one day's mistakes")
+    review.add_argument("--book", required=True)
+    review.add_argument("--day", required=True, help="YYYY-MM-DD")
+    review.add_argument("--out", default=None, help="output directory for the markdown")
+
+    sub.add_parser("version", help="print version")
+    return parser
+
+
+def _split_tags(value: str) -> tuple[str, ...]:
+    return tuple(tag.strip() for tag in value.split(",") if tag.strip())
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "version":
+        print(__version__)
+        return 0
+
+    if args.command == "add":
+        record = add_mistake(
+            args.book,
+            title=args.title,
+            issue=args.issue,
+            error_category=args.error_category,
+            date=args.date,
+            code=args.code,
+            industry=args.industry,
+            volatility=args.volatility,
+            market_cap=args.market_cap,
+            tags=_split_tags(args.tags),
+            cost=args.cost,
+            lesson=args.lesson,
+            situation=args.situation,
+        )
+        _print_json(record)
+        return 0
+
+    if args.command == "import-lessons":
+        result = import_lessons_markdown(args.from_path, args.book)
+        print(f"import: {result['imported']} imported, {result['skipped']} skipped")
+        return 0
+
+    if args.command == "match":
+        matches = match_lessons(
+            args.code,
+            args.industry,
+            args.volatility,
+            market_cap=args.market_cap,
+            tags=_split_tags(args.tags),
+            top_n=args.top_n,
+            path=args.book,
+            days_window=args.days_window,
+        )
+        if not matches:
+            print("match: no relevant lessons (this situation is new tuition)")
+            return 1
+        _print_json({"matches": matches})
+        return 0
+
+    if args.command == "review":
+        payload = review_day(args.book, args.day, out_dir=args.out)
+        _print_json(payload)
+        return 0
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())