brahman-buddy 0.2.6__tar.gz

brahman_buddy-0.2.6/LICENSE

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

brahman_buddy-0.2.6/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: brahman-buddy
+Version: 0.2.6
+Summary: A personal work buddy: Telegram, Lark and Feishu chats driving Claude Code, with scheduled jobs, short and long stories, and portable skills
+Author: Cong Zhang
+Author-email: Cong Zhang <13283869+congzhangzh@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: lark-oapi>=1.7.5
+Requires-Python: >=3.12

brahman_buddy-0.2.6/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "brahman-buddy"
+version = "0.2.6"
+license = "MIT"
+license-files = ["LICENSE"]
+description = "A personal work buddy: Telegram, Lark and Feishu chats driving Claude Code, with scheduled jobs, short and long stories, and portable skills"
+requires-python = ">=3.12"
+dependencies = ["lark-oapi>=1.7.5"]
+
+[[project.authors]]
+name = "Cong Zhang"
+email = "13283869+congzhangzh@users.noreply.github.com"
+
+[project.scripts]
+buddy = "work_brahman.cli:main"
+
+[tool.uv.build-backend]
+module-name = "work_brahman"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

brahman_buddy-0.2.6/pyproject.toml.orig

@@ -0,0 +1,31 @@
+[project]
+name = "brahman-buddy"
+version = "0.2.6"
+license = "MIT"
+license-files = ["LICENSE"]
+description = "A personal work buddy: Telegram, Lark and Feishu chats driving Claude Code, with scheduled jobs, short and long stories, and portable skills"
+authors = [
+    { name = "Cong Zhang", email = "13283869+congzhangzh@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "lark-oapi>=1.7.5",
+]
+
+[project.scripts]
+buddy = "work_brahman.cli:main"
+
+[tool.uv.build-backend]
+module-name = "work_brahman"  # the code keeps its name; the package on PyPI is brahman-buddy
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

brahman_buddy-0.2.6/src/work_brahman/__init__.py

@@ -0,0 +1 @@
+"""work_brahman: a small, extensible work buddy (Feishu/Lark + Claude Code)."""

brahman_buddy-0.2.6/src/work_brahman/__main__.py

@@ -0,0 +1,7 @@
+"""python -m work_brahman: the same as the buddy command (cli.main)."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

brahman_buddy-0.2.6/src/work_brahman/asks.py

@@ -0,0 +1,125 @@
+"""Asks: a question with buttons, sent to every chat of one person; the first answer wins.
+
+A job or duty runs as a child process that ends long before anyone answers, while the
+answer arrives in `buddy serve`. So an ask is a small file both can read:
+
+    $XDG_STATE_HOME/work_brahman/asks/<ask id>.json
+
+The child posts the card to each linked chat and writes what to do for each choice
+(`then`: a job or duty to run). When someone presses a button in any app, serve marks the
+first answer, changes every copy to "answered on Telegram: …", and starts what the choice
+asked for. A later press on another copy is told it was already answered. STOP closes
+every ask still open.
+"""
+
+import json
+import os
+import secrets
+import threading
+import time
+from pathlib import Path
+
+from .channel import Channel
+from .text import app, t
+
+_lock = threading.Lock()  # one answer at a time, in serve
+
+
+def create(state: Path, channels: list[Channel], chats: list[str], markdown: str, *,
+           title: str, options: list[list[str]], then: dict | None = None, run: str = "",
+           failed: bool = False, note: str = "") -> dict:
+    """Post the question to every chat. options: [[key, label], ...]; then: key -> [kind, name]."""
+    ask = {"id": f"{time.strftime('%m%d%H%M')}{secrets.token_hex(2)}", "run": run, "title": title,
+           "markdown": markdown, "options": options, "then": then or {}, "failed": failed,
+           "note": note, "asked": time.strftime("%Y-%m-%dT%H:%M:%S%z"), "copies": {},
+           "answer": None}
+    for chat in chats:
+        ch = next((c for c in channels if c.owns(chat)), None)
+        handle = ch.ask(chat, markdown, title=title, options=options, ask_id=ask["id"],
+                        failed=failed, note=note) if ch else None
+        if handle:
+            ask["copies"][chat] = handle
+    _save(state, ask)
+    return ask
+
+
+def answer(state: Path, channels: list[Channel], ask_id: str, choice: str, where: str,
+           who: str) -> tuple[str, dict | None]:
+    """Record the first answer and settle every copy. Returns (what to tell the presser,
+    the ask if this answer won, else None)."""
+    with _lock:
+        ask = load(state, ask_id)
+        if ask is None:
+            return t("ask.unknown"), None
+        if ask["answer"]:
+            a = ask["answer"]
+            return t("ask.already", said=_said(a)), None
+        label = dict(map(tuple, ask["options"])).get(choice)
+        if label is None:
+            return t("ask.bad_choice"), None
+        ask["answer"] = {"choice": choice, "label": label, "where": where, "who": who,
+                         "at": time.strftime("%Y-%m-%dT%H:%M:%S%z")}
+        _save(state, ask)
+    _settle_all(channels, ask, t("ask.settled", where=app(where), label=label))
+    return f"✓ {label}", ask
+
+
+def stop_all(state: Path, channels: list[Channel], where: str, who: str) -> int:
+    """Close every ask still open, as STOP does. Returns how many."""
+    closed = []
+    with _lock:
+        for f in sorted((state / "asks").glob("*.json")):
+            if time.time() - f.stat().st_mtime > 14 * 86400:  # Lark can't edit it any more
+                continue
+            ask = load(state, f.stem)
+            if ask and not ask["answer"]:
+                ask["answer"] = {"choice": "", "label": t("ask.stopped_label"), "where": where, "who": who,
+                                 "at": time.strftime("%Y-%m-%dT%H:%M:%S%z"), "stopped": True}
+                _save(state, ask)
+                closed.append(ask)
+    for ask in closed:
+        _settle_all(channels, ask, t("ask.stopped_line", where=app(where)))
+    return len(closed)
+
+
+def still_open(state: Path, title: str) -> dict | None:
+    """The unanswered ask with this title, if there is one: the same question is asked once,
+    and its card stands until it is answered."""
+    for f in sorted((state / "asks").glob("*.json"), reverse=True):
+        if time.time() - f.stat().st_mtime > 14 * 86400:  # as in stop_all: past editing
+            continue
+        ask = load(state, f.stem)
+        if ask and not ask["answer"] and ask["title"] == title:
+            return ask
+    return None
+
+
+def load(state: Path, ask_id: str) -> dict | None:
+    if not ask_id.isalnum():  # it came from a button press: never a path
+        return None
+    try:
+        return json.loads((state / "asks" / f"{ask_id}.json").read_text())
+    except (OSError, ValueError):
+        return None
+
+
+def _said(a: dict) -> str:
+    return (t("ask.stopped_from", where=app(a["where"])) if a.get("stopped")
+            else t("ask.answered_on", where=app(a["where"]), label=a["label"]))
+
+
+def _settle_all(channels: list[Channel], ask: dict, line: str) -> None:
+    """Every copy loses its buttons and says how the question was settled."""
+    for chat, handle in ask["copies"].items():
+        ch = next((c for c in channels if c.owns(chat)), None)
+        if ch:
+            ch.settle(chat, handle, ask["markdown"], title=ask["title"], line=line,
+                      failed=ask["failed"], note=ask["note"])
+
+
+def _save(state: Path, ask: dict) -> None:
+    d = state / "asks"
+    d.mkdir(parents=True, exist_ok=True)
+    tmp = d / f"{ask['id']}.tmp"
+    tmp.write_text(json.dumps(ask, indent=1, ensure_ascii=False))
+    os.replace(tmp, d / f"{ask['id']}.json")

brahman_buddy-0.2.6/src/work_brahman/bitable.py

@@ -0,0 +1,251 @@
+"""A Lark/Feishu Base (Bitable) as a workbench: the buddy's runs, asks, PRs, threads,
+workflows and short stories as tables, for Lark's own charts and dashboards.
+
+One way only, buddy -> Base. Every minute (and on `buddy bitable`) the rows are rebuilt
+from the files the buddy already writes (run records, asks, code-review.json,
+threads.json), and only rows that changed are sent: new ones created, changed ones
+updated, by a key per row. What was sent is remembered in state/bitable.json:
+
+    {"app": token, "url": ..., "tables": {name: table id}, "rows": {name: {key: [record id, hash]}}}
+
+On the first sync the buddy creates the Base in its own space and makes the person in
+[bitable] share_with a full-access collaborator. Needs the app scopes bitable:app and
+docs:permission.member:create. Rows never leave the tenant; the Base is as private as
+any document the bot owns.
+"""
+
+import hashlib
+import json
+import logging
+import threading
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+import lark_oapi as lark
+
+from . import short_stories as shorts
+from .runs import read as read_run
+
+log = logging.getLogger("buddy.bitable")
+
+STAMP = "%Y-%m-%dT%H:%M:%S%z"
+TEXT, NUMBER, SELECT, DATETIME, URL = 1, 2, 3, 5, 15
+# table -> [(field, type)], the first field is the row's key (the primary field)
+TABLES = {
+    "Runs": [("Run", TEXT), ("Workflow", TEXT), ("Kind", SELECT), ("Status", SELECT),
+             ("Started", DATETIME), ("Seconds", NUMBER), ("USD (list)", NUMBER), ("Tokens", NUMBER),
+             ("Denied", NUMBER), ("Trigger", TEXT), ("Result", TEXT), ("Version", TEXT)],
+    "Asks": [("Ask", TEXT), ("Title", TEXT), ("Question", TEXT), ("Options", TEXT),
+             ("Answer", TEXT), ("Where", SELECT), ("Asked", DATETIME), ("Answered", DATETIME),
+             ("Minutes to answer", NUMBER)],
+    "PRs": [("PR", TEXT), ("Link", URL), ("Repo", TEXT), ("Title", TEXT), ("CI", SELECT),
+            ("Review", SELECT), ("Merge", SELECT), ("Last comment", DATETIME)],
+    "Threads": [("Thread", TEXT), ("Link", URL), ("Kind", SELECT), ("Repo", TEXT),
+                ("Title", TEXT), ("Turn", SELECT), ("Last by", TEXT), ("At", DATETIME),
+                ("Mine", NUMBER)],
+    "Workflows": [("Workflow", TEXT), ("Schedule", TEXT), ("Runs (3 days)", NUMBER),
+                  ("Failed (3 days)", NUMBER), ("USD (3 days)", NUMBER),
+                  ("Tokens (3 days)", NUMBER), ("Last run", DATETIME), ("Last status", SELECT)],
+    # Short stories (short_stories.py): sessions' pipeline-bound work, one row per story
+    "Short stories": [("Story", TEXT), ("Title", TEXT), ("Status", SELECT), ("Who", TEXT),
+                      ("Started", DATETIME), ("Ended", DATETIME), ("Minutes", NUMBER),
+                      ("Marks done", NUMBER), ("Marks", NUMBER), ("Not planned", NUMBER),
+                      ("Replies", NUMBER), ("Stop from", SELECT), ("Last event", TEXT)],
+}
+FAILED = ("failed", "timeout", "interrupted")
+
+
+def _ms(stamp: str | None) -> int | None:
+    if not stamp:
+        return None
+    for fmt in (STAMP, "%Y-%m-%dT%H:%M:%SZ"):  # ours carry an offset; GitHub's end in Z (UTC)
+        try:
+            d = datetime.strptime(stamp, fmt)
+            return int((d if d.tzinfo else d.replace(tzinfo=UTC)).timestamp() * 1000)
+        except ValueError:
+            continue
+    return None
+
+
+def _read(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def rows(state: Path, cfg: dict, days: int = 30) -> dict[str, dict[str, dict]]:
+    """Every table's rows, {table: {key: fields}}, from the buddy's own files."""
+    out = {name: {} for name in TABLES}
+    runs = []
+    for d in sorted((state / "runs").glob("*"))[-days:]:
+        runs += [read_run(r) for r in (_read(f) for f in d.glob("*.json")) if r.get("id")]
+    for r in runs:
+        f = r.get("fitness") or {}
+        out["Runs"][r["id"]] = {
+            "Workflow": f"{r['kind']}:{r['name']}", "Kind": r["kind"], "Status": r["status"],
+            "Started": _ms(r.get("started")), "Seconds": f.get("seconds"),
+            "USD (list)": round(f.get("usd_list") or 0, 4),
+            "Tokens": sum(f.get(k) or 0 for k in ("tokens_in", "tokens_cached", "tokens_out")),
+            "Denied": f.get("denied") or 0, "Trigger": r.get("trigger", ""),
+            "Result": str(r.get("result") or r.get("error") or "")[:500], "Version": r.get("version", "")}
+    for f in (state / "asks").glob("*.json"):
+        a = _read(f)
+        if not a.get("id"):
+            continue
+        ans = a.get("answer") or {}
+        asked, answered = _ms(a.get("asked")), _ms(ans.get("at"))
+        out["Asks"][a["id"]] = {
+            "Title": a.get("title", ""), "Question": a.get("markdown", "")[:1000],
+            "Options": " / ".join(label for _, label in a.get("options", [])),
+            "Answer": ans.get("label", ""), "Where": ans.get("where", "") or "open",
+            "Asked": asked, "Answered": answered,
+            "Minutes to answer": round((answered - asked) / 60000, 1) if asked and answered else None}
+    for pr in _read(state / "code-review.json").get("prs", {}).values():
+        talk = pr.get("talk") or []
+        out["PRs"][pr["key"]] = {
+            "Link": {"text": pr["url"], "link": pr["url"]}, "Repo": pr["repo"], "Title": pr["title"],
+            "CI": pr["ci"], "Review": pr["review"], "Merge": pr["merge"],
+            "Last comment": _ms(talk[-1]["at"]) if talk else None}
+    for url, t in _read(state / "threads.json").get("items", {}).items():
+        out["Threads"][f"{t['repo']}#{t['number']}"] = {
+            "Link": {"text": url, "link": url}, "Kind": t["kind"], "Repo": t["repo"],
+            "Title": t["title"], "Turn": t["turn"], "Last by": t.get("last") or "",
+            "At": _ms(t.get("at")), "Mine": t.get("mine") or 0}
+    since = time.time() - 3 * 86400
+    for kind, section in (("job", "jobs"), ("duty", "duties")):
+        for name, t in cfg.get(section, {}).items():
+            rs = [r for r in runs if r["kind"] == kind and r["name"] == name]
+            recent = [r for r in rs if (_ms(r.get("started")) or 0) / 1000 >= since]
+            last = max(rs, key=lambda r: r.get("started", ""), default=None)
+            fit = [r.get("fitness") or {} for r in recent]
+            out["Workflows"][f"{kind}:{name}"] = {
+                "Schedule": t.get("schedule", "not scheduled"), "Runs (3 days)": len(recent),
+                "Failed (3 days)": sum(r["status"] in FAILED for r in recent),
+                "USD (3 days)": round(sum(f.get("usd_list") or 0 for f in fit), 4),
+                "Tokens (3 days)": sum(f.get(k) or 0 for f in fit for k in ("tokens_in", "tokens_cached", "tokens_out")),
+                "Last run": _ms(last.get("started")) if last else None,
+                "Last status": last["status"] if last else "never"}
+    # A family is a workflow too, and its stories are its runs (the web's level 1 does the same).
+    now = int(time.time() * 1000)
+    for s in shorts.all_stories(state):
+        status = "stopped" if s["status"] == "failed" and s.get("stop") else s["status"]
+        started, ended = _ms(s["started"]), _ms(s["ended"])
+        out["Short stories"][f"#{s['id']}"] = {
+            "Title": s["title"], "Status": status, "Who": s.get("who") or "", "Started": started,
+            "Ended": ended, "Minutes": round(((ended or now) - started) / 60000, 1) if started else None,
+            "Marks done": sum(m["status"] in ("done", "skipped") for m in s["marks"]),
+            "Marks": len(s["marks"]), "Not planned": sum(not m.get("planned", True) for m in s["marks"]),
+            "Replies": len(s.get("replies", [])), "Stop from": (s.get("stop") or {}).get("where"),
+            "Last event": s["events"][-1]["text"][:500] if s["events"] else ""}
+    recent = [r for r in out["Short stories"].values() if (r.get("Started") or 0) / 1000 >= since]
+    last = max(out["Short stories"].values(), key=lambda r: r.get("Started") or 0, default=None)
+    out["Workflows"]["family:short-story"] = {
+        "Schedule": "started by sessions", "Runs (3 days)": len(recent),
+        "Failed (3 days)": sum(r["Status"] in ("failed", "stopped") for r in recent),
+        "USD (3 days)": 0, "Tokens (3 days)": 0,  # the buddy only keeps the board: no agent of its own
+        "Last run": last.get("Started") if last else None,
+        "Last status": last["Status"] if last else "never"}
+    # Lark rejects null values; an empty cell is simply left out
+    return {t: {k: {f: v for f, v in fields.items() if v is not None} for k, fields in rs.items()}
+            for t, rs in out.items()}
+
+
+class Bitable:
+    def __init__(self, app_id: str, app_secret: str, domain, state: Path, cfg: dict):
+        self.api = (lark.Client.builder().app_id(app_id).app_secret(app_secret).domain(domain)
+                    .log_level(lark.LogLevel.WARNING).build())
+        self.state, self.cfg = state, cfg
+        self.share_with = cfg.get("bitable", {}).get("share_with", "")
+        self.path = state / "bitable.json"
+        self.lock = threading.Lock()
+
+    def start(self, every: int = 60) -> None:
+        def loop():
+            while True:
+                try:
+                    n = self.sync()
+                    if n:
+                        log.info("bitable: %d rows sent", n)
+                except Exception:
+                    log.exception("bitable sync failed")
+                time.sleep(every)
+        threading.Thread(target=loop, name="bitable", daemon=True).start()
+
+    def sync(self) -> int:
+        """Create the Base on the first call, then send what changed. Returns rows sent."""
+        with self.lock:
+            st = _read(self.path) or {"rows": {}}
+            if not st.get("app"):
+                self._create(st)
+                self._save(st)
+            for name in TABLES.keys() - st["tables"].keys():  # added since the Base was made
+                self._table(st, name)
+                self._save(st)
+            sent = 0
+            for table, want in rows(self.state, self.cfg).items():
+                have = st["rows"].setdefault(table, {})
+                new, changed = [], []
+                for key, fields in want.items():
+                    fields = {TABLES[table][0][0]: key, **fields}
+                    h = hashlib.sha1(json.dumps(fields, sort_keys=True).encode()).hexdigest()[:12]
+                    if key not in have:
+                        new.append((key, fields, h))
+                    elif have[key][1] != h:
+                        changed.append((key, fields, h))
+                tid = st["tables"][table]
+                for i in range(0, len(new), 500):
+                    part = new[i:i + 500]
+                    made = self._call("POST", f"/apps/{st['app']}/tables/{tid}/records/batch_create",
+                                      {"records": [{"fields": f} for _, f, _ in part]})["records"]
+                    for (key, _, h), rec in zip(part, made):
+                        have[key] = [rec["record_id"], h]
+                for i in range(0, len(changed), 500):
+                    part = changed[i:i + 500]
+                    self._call("POST", f"/apps/{st['app']}/tables/{tid}/records/batch_update",
+                               {"records": [{"record_id": have[k][0], "fields": f} for k, f, _ in part]})
+                    for key, _, h in part:
+                        have[key][1] = h
+                sent += len(new) + len(changed)
+                self._save(st)
+            return sent
+
+    def url(self) -> str:
+        return _read(self.path).get("url", "")
+
+    def _create(self, st: dict) -> None:
+        app = self._call("POST", "/apps", {"name": "brahman workbench"})["app"]
+        st.update(app=app["app_token"], url=app.get("url", ""), tables={}, rows={})
+        for name in TABLES:
+            self._table(st, name)
+        if app.get("default_table_id"):  # the empty table every new Base starts with
+            self._call("DELETE", f"/apps/{app['app_token']}/tables/{app['default_table_id']}", None)
+        if self.share_with:
+            self._call("POST", f"/permissions/{app['app_token']}/members?type=bitable&need_notification=true",
+                       {"member_type": "openid", "member_id": self.share_with, "perm": "full_access"},
+                       base="/open-apis/drive/v1")
+        log.info("bitable: created %s", st["url"])
+
+    def _table(self, st: dict, name: str) -> None:
+        t = self._call("POST", f"/apps/{st['app']}/tables", {"table": {
+            "name": name, "default_view_name": "All",
+            "fields": [{"field_name": f, "type": kind} for f, kind in TABLES[name]]}})
+        st["tables"][name] = t["table_id"]
+        log.info("bitable: table %s added", name)
+
+    def _call(self, method: str, path: str, body, base: str = "/open-apis/bitable/v1") -> dict:
+        req = (lark.BaseRequest.builder().http_method(getattr(lark.HttpMethod, method))
+               .uri(base + path).token_types({lark.AccessTokenType.TENANT}))
+        if body is not None:
+            req = req.body(body)
+        resp = self.api.request(req.build())
+        d = json.loads(resp.raw.content or b"{}")
+        if d.get("code"):
+            raise RuntimeError(f"lark {method} {path.split('?')[0]}: {d.get('code')} {d.get('msg')}")
+        return d.get("data") or {}
+
+    def _save(self, st: dict) -> None:
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(st, ensure_ascii=False))
+        tmp.replace(self.path)