recipebrain 0.0.1__tar.gz

recipebrain-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 <YOUR NAME>
+
+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.

recipebrain-0.0.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: recipebrain
+Version: 0.0.1
+Summary: Personal Swiss recipe knowledge base with promotion-aware meal planning, exposed via MCP. Companion to cellarbrain.
+License-Expression: MIT
+Keywords: recipes,mcp,swiss,meal-planning,duckdb,parquet,personal-data
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=1.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: tomli>=2; python_version < "3.11"
+Requires-Dist: httpx>=0.27
+Requires-Dist: selectolax>=0.3
+Requires-Dist: extruct>=0.16
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Provides-Extra: ocr
+Requires-Dist: pytesseract; extra == "ocr"
+Requires-Dist: Pillow; extra == "ocr"
+Provides-Extra: llm
+Requires-Dist: openai>=1.30; extra == "llm"
+Dynamic: license-file
+
+# recipebrain
+
+Personal Swiss recipe knowledge base with promotion-aware meal planning, exposed via MCP.
+
+**Companion to [cellarbrain](https://github.com/<owner>/cellarbrain).** Standalone — no Python coupling. Interop via MCP at runtime, orchestrated by the chat host.
+
+## Status
+
+**Pre-alpha.** Skeleton only. No scraping, no real MCP tools, no queries yet.
+
+## Quickstart
+
+```bash
+git clone https://github.com/<owner>/recipebrain.git
+cd recipebrain
+python -m venv .venv
+.venv/Scripts/activate   # Windows
+# source .venv/bin/activate  # macOS/Linux
+pip install -e ".[dev]"
+cp recipebrain.toml.example recipebrain.toml
+pytest
+recipebrain --help
+```
+
+## Documentation
+
+| Doc | Topic |
+|-----|-------|
+| [docs/01-vision-and-usecases.md](docs/01-vision-and-usecases.md) | Vision, user persona, 10 use cases |
+| [docs/02-requirements.md](docs/02-requirements.md) | Functional & non-functional requirements |
+| [docs/03-data-sources.md](docs/03-data-sources.md) | Swiss recipe & promotion sources |
+| [docs/04-entity-model.md](docs/04-entity-model.md) | Parquet table schemas, views |
+| [docs/05-mcp-tools.md](docs/05-mcp-tools.md) | 15 MCP tools + resources |
+| [docs/06-architecture.md](docs/06-architecture.md) | Pipeline, modules, build phasing |
+| [docs/decisions/](docs/decisions/) | Architecture Decision Records |
+
+## Relationship to cellarbrain
+
+recipebrain and cellarbrain are independent Python packages that interoperate via MCP:
+
+- **cellarbrain** answers "which wine pairs with this dish?"
+- **recipebrain** answers "which dish pairs with this wine I want to open?"
+- Together (both MCP servers configured in the same host) = end-to-end meal planning with wine pairing.
+
+No shared library. No Python imports between them. The chat host orchestrates cross-server tool calls. See [docs/06-architecture.md](docs/06-architecture.md) for details.
+
+## Privacy
+
+All data stays local. No cloud sync, no telemetry, no accounts. Recipe data is scraped from public websites and stored as local Parquet files. Your cook log, pantry, and preferences never leave your machine.
+
+## Releasing
+
+PyPI publishing uses trusted publishers (OIDC). Configure the `pypi` environment in GitHub repo settings with PyPI's trusted publisher binding. Then push a version tag:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+The `publish.yml` workflow handles the rest.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

recipebrain-0.0.1/README.md

@@ -0,0 +1,64 @@
+# recipebrain
+
+Personal Swiss recipe knowledge base with promotion-aware meal planning, exposed via MCP.
+
+**Companion to [cellarbrain](https://github.com/<owner>/cellarbrain).** Standalone — no Python coupling. Interop via MCP at runtime, orchestrated by the chat host.
+
+## Status
+
+**Pre-alpha.** Skeleton only. No scraping, no real MCP tools, no queries yet.
+
+## Quickstart
+
+```bash
+git clone https://github.com/<owner>/recipebrain.git
+cd recipebrain
+python -m venv .venv
+.venv/Scripts/activate   # Windows
+# source .venv/bin/activate  # macOS/Linux
+pip install -e ".[dev]"
+cp recipebrain.toml.example recipebrain.toml
+pytest
+recipebrain --help
+```
+
+## Documentation
+
+| Doc | Topic |
+|-----|-------|
+| [docs/01-vision-and-usecases.md](docs/01-vision-and-usecases.md) | Vision, user persona, 10 use cases |
+| [docs/02-requirements.md](docs/02-requirements.md) | Functional & non-functional requirements |
+| [docs/03-data-sources.md](docs/03-data-sources.md) | Swiss recipe & promotion sources |
+| [docs/04-entity-model.md](docs/04-entity-model.md) | Parquet table schemas, views |
+| [docs/05-mcp-tools.md](docs/05-mcp-tools.md) | 15 MCP tools + resources |
+| [docs/06-architecture.md](docs/06-architecture.md) | Pipeline, modules, build phasing |
+| [docs/decisions/](docs/decisions/) | Architecture Decision Records |
+
+## Relationship to cellarbrain
+
+recipebrain and cellarbrain are independent Python packages that interoperate via MCP:
+
+- **cellarbrain** answers "which wine pairs with this dish?"
+- **recipebrain** answers "which dish pairs with this wine I want to open?"
+- Together (both MCP servers configured in the same host) = end-to-end meal planning with wine pairing.
+
+No shared library. No Python imports between them. The chat host orchestrates cross-server tool calls. See [docs/06-architecture.md](docs/06-architecture.md) for details.
+
+## Privacy
+
+All data stays local. No cloud sync, no telemetry, no accounts. Recipe data is scraped from public websites and stored as local Parquet files. Your cook log, pantry, and preferences never leave your machine.
+
+## Releasing
+
+PyPI publishing uses trusted publishers (OIDC). Configure the `pypi` environment in GitHub repo settings with PyPI's trusted publisher binding. Then push a version tag:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+The `publish.yml` workflow handles the rest.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

recipebrain-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools >= 68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recipebrain"
+version = "0.0.1"
+description = "Personal Swiss recipe knowledge base with promotion-aware meal planning, exposed via MCP. Companion to cellarbrain."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["recipes", "mcp", "swiss", "meal-planning", "duckdb", "parquet", "personal-data"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "duckdb >= 1.0",
+    "pyarrow >= 15",
+    "tomli >= 2; python_version < '3.11'",
+    "httpx >= 0.27",
+    "selectolax >= 0.3",
+    "extruct >= 0.16",
+    "mcp >= 1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest >= 8", "pytest-cov", "ruff >= 0.5", "mypy >= 1.10"]
+ocr = ["pytesseract", "Pillow"]
+llm = ["openai >= 1.30"]
+
+[project.scripts]
+recipebrain = "recipebrain.cli:main"
+
+[tool.setuptools.package-data]
+recipebrain = ["skills/**/*.md", "skills/README.md"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+python_version = "3.11"
+strict = false
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = ["extruct.*"]
+ignore_missing_imports = true

recipebrain-0.0.1/setup.cfg

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

recipebrain-0.0.1/setup.py

@@ -0,0 +1,63 @@
+"""Custom build hook: sync .openclaw/ skills before packaging."""
+
+from __future__ import annotations
+
+import pathlib
+import shutil
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+from setuptools.command.sdist import sdist
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent
+SRC_DIR = REPO_ROOT / ".openclaw"
+DST_DIR = REPO_ROOT / "src" / "recipebrain" / "skills"
+SKIP = {"_archive", "__pycache__"}
+
+
+def _sync_skills() -> None:
+    """One-way sync .openclaw/ -> src/recipebrain/skills/."""
+    if not SRC_DIR.is_dir():
+        return
+
+    DST_DIR.mkdir(parents=True, exist_ok=True)
+
+    readme = SRC_DIR / "README.md"
+    if readme.is_file():
+        shutil.copy2(readme, DST_DIR / "README.md")
+
+    for child in sorted(SRC_DIR.iterdir()):
+        if not child.is_dir():
+            continue
+        if child.name in SKIP or child.name.startswith("."):
+            continue
+        skill_file = child / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        dst_skill_dir = DST_DIR / child.name
+        dst_skill_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(skill_file, dst_skill_dir / "SKILL.md")
+
+
+class SyncSkillsBuildPy(build_py):
+    """Run skill sync before build_py."""
+
+    def run(self) -> None:
+        _sync_skills()
+        super().run()
+
+
+class SyncSkillsSdist(sdist):
+    """Run skill sync before sdist."""
+
+    def run(self) -> None:
+        _sync_skills()
+        super().run()
+
+
+setup(
+    cmdclass={
+        "build_py": SyncSkillsBuildPy,
+        "sdist": SyncSkillsSdist,
+    },
+)

recipebrain-0.0.1/src/recipebrain/__init__.py

@@ -0,0 +1,6 @@
+"""recipebrain — personal Swiss recipe knowledge base, exposed via MCP."""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+__all__ = ["__version__"]

recipebrain-0.0.1/src/recipebrain/__main__.py

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

recipebrain-0.0.1/src/recipebrain/cli.py

@@ -0,0 +1,319 @@
+"""CLI entry point for recipebrain.
+
+Subcommands mirror the planned tool surface in docs/05-mcp-tools.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from recipebrain import __version__
+
+
+def _stub(name: str) -> int:
+    print(f"recipebrain {name}: not yet implemented — see docs/06-architecture.md build phasing")
+    return 0
+
+
+def _cmd_etl(args: argparse.Namespace) -> int:
+    from recipebrain.etl import run_etl
+    from recipebrain.settings import Settings
+
+    settings = Settings.load(args.config)
+    results = run_etl(settings, source_filter=args.source, limit=args.limit)
+
+    if not results:
+        print("No sources processed.")
+        return 0
+
+    for r in results:
+        print(
+            f"  {r.source}: discovered={r.discovered} fetched={r.fetched} "
+            f"skipped={r.skipped} errors={r.errors}"
+        )
+        for detail in r.error_details:
+            print(f"    ! {detail}")
+
+    total_errors = sum(r.errors for r in results)
+    return 1 if total_errors > 0 and all(r.fetched == 0 for r in results) else 0
+
+
+def _cmd_promotions_refresh(args: argparse.Namespace) -> int:
+    return _stub("promotions refresh")
+
+
+def _cmd_ingest(args: argparse.Namespace) -> int:
+    return _stub("ingest")
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from recipebrain.settings import Settings
+    from recipebrain.validate import validate
+
+    settings = Settings.load(args.config)
+    output_dir = Path(settings.paths.output_dir)
+    result = validate(output_dir)
+
+    if result.ok:
+        print(f"All checks passed ({result.checks_run} checks).")
+        return 0
+
+    print(f"Validation found {len(result.issues)} issue(s) ({result.checks_run} checks):")
+    for issue in result.issues:
+        print(f"  ! {issue}")
+    return 1
+
+
+def _cmd_mcp(args: argparse.Namespace) -> int:
+    import os
+    from pathlib import Path
+
+    from recipebrain.settings import Settings
+
+    # Resolve paths to absolute before starting MCP server — the server
+    # may be launched by an external client with a different CWD.
+    settings = Settings.load(args.config)
+    os.environ["RECIPEBRAIN_OUTPUT_DIR"] = str(Path(settings.paths.output_dir).resolve())
+    if args.config:
+        os.environ["RECIPEBRAIN_CONFIG"] = str(Path(args.config).resolve())
+
+    from recipebrain.mcp_server import run
+
+    return run()
+
+
+def _cmd_reindex(args: argparse.Namespace) -> int:
+    return _stub("reindex")
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from recipebrain.doctor import Severity, run_doctor
+    from recipebrain.settings import Settings
+
+    settings = Settings.load(args.config)
+    report = run_doctor(
+        output_dir=Path(settings.paths.output_dir),
+        snapshot_dir=Path(settings.paths.snapshot_dir),
+        dossier_dir=Path(settings.paths.dossier_dir),
+    )
+
+    icons = {Severity.OK: "✓", Severity.WARN: "!", Severity.ERROR: "✗"}
+    for check in report.checks:
+        icon = icons[check.severity]
+        print(f"  {icon} {check.name}: {check.message}")
+
+    if report.ok:
+        print("\nAll checks passed.")
+        return 0
+    print(f"\n{report.worst.value.upper()}: some checks need attention.")
+    return 1 if report.worst == Severity.ERROR else 0
+
+
+def _cmd_info(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from recipebrain.info import format_info, gather_info
+    from recipebrain.settings import Settings
+
+    settings = Settings.load(args.config)
+    report = gather_info(Path(settings.paths.output_dir))
+    print(format_info(report))
+    return 0
+
+
+def _cmd_snapshot(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from recipebrain.settings import Settings
+    from recipebrain.snapshot import create_snapshot, list_snapshots, restore_snapshot
+
+    settings = Settings.load(args.config)
+    output_dir = Path(settings.paths.output_dir)
+    snapshot_dir = Path(settings.paths.snapshot_dir)
+
+    action = getattr(args, "snapshot_action", None) or "create"
+
+    if action == "list":
+        snaps = list_snapshots(snapshot_dir)
+        if not snaps:
+            print("No snapshots found.")
+            return 0
+        for s in snaps:
+            print(f"  {s['name']}  ({s['file_count']} files)")
+        return 0
+
+    if action == "restore":
+        name = args.name
+        snap_path = snapshot_dir / name
+        try:
+            count = restore_snapshot(snap_path, output_dir)
+            print(f"Restored {count} file(s) from snapshot '{name}'.")
+            return 0
+        except FileNotFoundError as exc:
+            print(f"Error: {exc}")
+            return 1
+
+    # Default: create
+    label = getattr(args, "label", None)
+    result = create_snapshot(output_dir, snapshot_dir, label=label)
+    if result is None:
+        print("Nothing to snapshot (no parquet files found).")
+        return 0
+    print(f"Snapshot created: {result.name}")
+    return 0
+
+
+def _cmd_install_skills(args: argparse.Namespace) -> int:
+    from pathlib import Path
+
+    from recipebrain.install_skills import install
+
+    target = Path(args.target) if args.target else None
+    count = install(target=target, force=args.force)
+    if count < 0:
+        return 1
+    print(f"Installed {count} skill file(s).")
+    return 0
+
+
+def _cmd_log(args: argparse.Namespace) -> int:
+    from recipebrain.mcp_server import log_cook
+
+    result = log_cook(
+        recipe_id=args.recipe_id,
+        rating=args.rating,
+        notes=args.notes,
+        servings=args.servings,
+        scale_factor=args.scale_factor,
+    )
+    print(result)
+    return 1 if result.startswith("Error") else 0
+
+
+def _cmd_dashboard(args: argparse.Namespace) -> int:
+    from recipebrain.dashboard import run_dashboard
+
+    host = args.host
+    port = args.port
+    print(f"Starting dashboard at http://{host}:{port}")
+    run_dashboard(host=host, port=port)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="recipebrain",
+        description="Personal Swiss recipe knowledge base with promotion-aware meal planning.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--config",
+        "-c",
+        default="recipebrain.toml",
+        help="Path to config file (default: recipebrain.toml)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # etl
+    sp_etl = subparsers.add_parser("etl", help="Run ETL pipeline for recipe sources")
+    sp_etl.add_argument("--source", "-s", help="Specific source to scrape (default: all enabled)")
+    sp_etl.add_argument(
+        "--limit",
+        "-l",
+        type=int,
+        default=None,
+        help="Max new recipes to fetch per source (default: unlimited)",
+    )
+    sp_etl.set_defaults(func=_cmd_etl)
+
+    # promotions
+    sp_promo = subparsers.add_parser("promotions", help="Manage promotion data")
+    promo_sub = sp_promo.add_subparsers(dest="promotions_command")
+    sp_promo_refresh = promo_sub.add_parser("refresh", help="Refresh promotion data")
+    sp_promo_refresh.set_defaults(func=_cmd_promotions_refresh)
+    sp_promo.set_defaults(func=_cmd_promotions_refresh)
+
+    # ingest
+    sp_ingest = subparsers.add_parser("ingest", help="Ingest a recipe from file or URL")
+    sp_ingest.add_argument("target", help="File path or URL to ingest")
+    sp_ingest.set_defaults(func=_cmd_ingest)
+
+    # validate
+    sp_validate = subparsers.add_parser("validate", help="Validate data integrity")
+    sp_validate.set_defaults(func=_cmd_validate)
+
+    # mcp
+    sp_mcp = subparsers.add_parser("mcp", help="Start MCP server")
+    sp_mcp.set_defaults(func=_cmd_mcp)
+
+    # reindex
+    sp_reindex = subparsers.add_parser("reindex", help="Rebuild search indexes")
+    sp_reindex.set_defaults(func=_cmd_reindex)
+
+    # doctor
+    sp_doctor = subparsers.add_parser("doctor", help="Run health checks on data and config")
+    sp_doctor.set_defaults(func=_cmd_doctor)
+
+    # info
+    sp_info = subparsers.add_parser("info", help="Show version, environment, and data summary")
+    sp_info.set_defaults(func=_cmd_info)
+
+    # snapshot
+    sp_snapshot = subparsers.add_parser("snapshot", help="Create or manage data snapshots")
+    snap_sub = sp_snapshot.add_subparsers(dest="snapshot_action")
+    sp_snap_create = snap_sub.add_parser("create", help="Create a new snapshot")
+    sp_snap_create.add_argument("--label", "-l", default=None, help="Label for the snapshot")
+    snap_sub.add_parser("list", help="List available snapshots")
+    sp_snap_restore = snap_sub.add_parser("restore", help="Restore a snapshot")
+    sp_snap_restore.add_argument("name", help="Snapshot name to restore")
+    sp_snapshot.set_defaults(func=_cmd_snapshot)
+
+    # install-skills
+    sp_skills = subparsers.add_parser("install-skills", help="Install OpenClaw skills")
+    sp_skills.add_argument(
+        "--target",
+        "-t",
+        default=None,
+        help="Target directory (default: ~/.openclaw/skills/recipebrain/)",
+    )
+    sp_skills.add_argument("--force", action="store_true", help="Overwrite existing skill files")
+    sp_skills.set_defaults(func=_cmd_install_skills)
+
+    # log
+    sp_log = subparsers.add_parser("log", help="Log a cook event for a recipe")
+    sp_log.add_argument("recipe_id", type=int, help="ID of the recipe cooked")
+    sp_log.add_argument("--rating", "-r", type=int, default=None, help="Rating 1-5")
+    sp_log.add_argument("--notes", "-n", default=None, help="Free-form notes")
+    sp_log.add_argument("--servings", "-s", type=int, default=None, help="Number of servings made")
+    sp_log.add_argument(
+        "--scale-factor", type=float, default=None, help="Scale multiplier (e.g. 2.0 for doubled)"
+    )
+    sp_log.set_defaults(func=_cmd_log)
+
+    # dashboard
+    sp_dash = subparsers.add_parser("dashboard", help="Start observability dashboard")
+    sp_dash.add_argument("--host", default="127.0.0.1", help="Bind host (default: 127.0.0.1)")
+    sp_dash.add_argument("--port", "-p", type=int, default=8777, help="Bind port (default: 8777)")
+    sp_dash.set_defaults(func=_cmd_dashboard)
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    # Initialise structured logging before running any command
+    from recipebrain.log import setup_logging
+
+    setup_logging()
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())