Rebuild: finance manager chat assistant with HF CSV storage and Telegram bot

- app.py: Gradio Blocks with Chat + Ledger tabs, HF OAuth login, streaming responses
- ledger.py: thread-safe CSV ledger with HF Hub dataset persistence (HF_LEDGER_REPO)
- agent.py: finance assistant system prompt, streaming + batch LLM calls, action parsing
- bot.py: Telegram bot running as daemon thread, per-user conversation history
- requirements.txt: huggingface-hub, pandas, python-telegram-bot, python-dotenv

Co-Authored-By: Oz <oz-agent@warp.dev>

README.md

@@ -1,8 +1,8 @@
 ---
-title: Financemanager
-emoji: 💬
-colorFrom: yellow
-colorTo: purple
+title: Finance Manager
+emoji: 💸
+colorFrom: green
+colorTo: blue
 sdk: gradio
 sdk_version: 6.5.1
 app_file: app.py
@@ -12,4 +12,23 @@ hf_oauth_scopes:
 - inference-api
 ---
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+# 💸 Finance Manager
+
+A personal finance assistant with natural language expense logging, persistent CSV storage on HuggingFace Hub, and a Telegram bot interface.
+
+## Features
+
+- **Chat UI** — describe expenses in plain English; the AI parses and logs them
+- **Ledger tab** — view all entries, refresh on demand
+- **Telegram bot** — same assistant available in Telegram
+- **Persistent storage** — ledger CSV synced to a private HF dataset repo
+
+## Required Secrets (Space Settings → Repository secrets)
+
+| Secret | Purpose |
+|---|---|
+| `HF_TOKEN` | Token with write access to your ledger dataset repo |
+| `HF_LEDGER_REPO` | Dataset repo ID for CSV storage, e.g. `username/finance-ledger` |
+| `TELEGRAM_BOT_TOKEN` | Optional — Telegram bot token from @BotFather |
+
+Without `HF_TOKEN` + `HF_LEDGER_REPO`, entries are saved to `/tmp` and will not survive a Space restart.

agent.py

@@ -0,0 +1,117 @@
+"""Finance assistant: LLM-backed expense parsing and ledger actions."""
+
+import json
+import re
+import logging
+from datetime import datetime
+from typing import Generator
+from huggingface_hub import InferenceClient
+
+from ledger import Ledger
+
+logger = logging.getLogger(__name__)
+
+MODEL = "openai/gpt-oss-20b"
+
+SYSTEM = """\
+You are a personal finance assistant. Help the user log expenses, query spending summaries, and manage their ledger.
+
+When the user describes an expense, extract it and include a JSON action block in your response:
+```json
+{"action": "add", "date": "YYYY-MM-DD", "description": "...", "category": "Food|Transport|Utilities|Entertainment|Health|Shopping|Rent|Other", "amount": 0.00}
+```
+
+When the user wants to undo or delete the last entry:
+```json
+{"action": "delete_last"}
+```
+
+Use today's date if none is given. Keep replies brief and friendly.
+If the user asks about their spending, use the ledger context below to answer accurately.
+If no ledger action is needed, just respond conversationally — no JSON block."""
+
+
+# ── context & parsing ─────────────────────────────────────────────────────────
+
+def _ledger_context(ledger: Ledger) -> str:
+    if ledger.df.empty:
+        return "Ledger is empty."
+    total = ledger.total()
+    by_cat = ledger.by_category()
+    cat_str = " | ".join(
+        f"{k} ${v:.2f}" for k, v in sorted(by_cat.items(), key=lambda x: -x[1])
+    )
+    recent = ledger.recent(5).to_string(index=False)
+    return f"Total: ${total:.2f}  |  {cat_str}\nRecent entries:\n{recent}"
+
+
+def _parse_action(text: str) -> dict | None:
+    m = re.search(r"```json\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if m:
+        try:
+            return json.loads(m.group(1))
+        except json.JSONDecodeError:
+            pass
+    return None
+
+
+def _clean(text: str) -> str:
+    """Strip JSON action blocks from visible reply."""
+    return re.sub(r"```json.*?```", "", text, flags=re.DOTALL).strip()
+
+
+def _build_messages(message: str, history: list[dict], ledger: Ledger) -> list[dict]:
+    system = SYSTEM + "\n\nCurrent ledger:\n" + _ledger_context(ledger)
+    return [{"role": "system", "content": system}] + history + [{"role": "user", "content": message}]
+
+
+# ── actions ───────────────────────────────────────────────────────────────────
+
+def execute(action: dict, ledger: Ledger, fallback_desc: str = "") -> str:
+    """Run a parsed action against the ledger. Returns a confirmation string."""
+    if action.get("action") == "add":
+        ok = ledger.add(
+            date=action.get("date", datetime.now().strftime("%Y-%m-%d")),
+            description=action.get("description", fallback_desc),
+            category=action.get("category", "Other"),
+            amount=float(action.get("amount", 0)),
+        )
+        if ok:
+            return f"✅ Logged **{action.get('category')}** — ${float(action.get('amount', 0)):.2f}"
+        return "❌ Failed to save entry."
+
+    if action.get("action") == "delete_last":
+        return "🗑️ Last entry removed." if ledger.delete_last() else "Nothing to delete."
+
+    return ""
+
+
+# ── inference ─────────────────────────────────────────────────────────────────
+
+def stream_response(
+    message: str, history: list[dict], ledger: Ledger, token: str
+) -> Generator[tuple[str, dict | None], None, None]:
+    """
+    Yields (partial_reply, action) tuples.
+    action is None on all intermediate yields; populated only on the final yield.
+    """
+    client = InferenceClient(token=token, model=MODEL)
+    messages = _build_messages(message, history, ledger)
+
+    accumulated = ""
+    for chunk in client.chat_completion(messages, max_tokens=512, stream=True, temperature=0.2):
+        if chunk.choices and chunk.choices[0].delta.content:
+            accumulated += chunk.choices[0].delta.content
+            yield _clean(accumulated), None
+
+    yield _clean(accumulated), _parse_action(accumulated)
+
+
+def batch_response(
+    message: str, history: list[dict], ledger: Ledger, token: str
+) -> tuple[str, dict | None]:
+    """Synchronous single-call variant used by the Telegram bot."""
+    client = InferenceClient(token=token, model=MODEL)
+    messages = _build_messages(message, history, ledger)
+    raw = client.chat_completion(messages, max_tokens=512, temperature=0.2).choices[0].message.content
+    return _clean(raw), _parse_action(raw)

app.py

@@ -1,68 +1,66 @@
+"""Gradio web UI for the personal finance manager."""
+
+import os
+import threading
 import gradio as gr
-from huggingface_hub import InferenceClient
-
-
-def respond(
-    message,
-    history: list[dict[str, str]],
-    system_message,
-    max_tokens,
-    temperature,
-    top_p,
-    hf_token: gr.OAuthToken,
-):
-    """
-    For more information on `huggingface_hub` Inference API support, please check the docs: https://huggingface.co/docs/huggingface_hub/v0.22.2/en/guides/inference
-    """
-    client = InferenceClient(token=hf_token.token, model="openai/gpt-oss-20b")
-
-    messages = [{"role": "system", "content": system_message}]
-
-    messages.extend(history)
-
-    messages.append({"role": "user", "content": message})
-
-    response = ""
-
-    for message in client.chat_completion(
-        messages,
-        max_tokens=max_tokens,
-        stream=True,
-        temperature=temperature,
-        top_p=top_p,
-    ):
-        choices = message.choices
-        token = ""
-        if len(choices) and choices[0].delta.content:
-            token = choices[0].delta.content
-
-        response += token
-        yield response
-
-
-"""
-For information on how to customize the ChatInterface, peruse the gradio docs: https://www.gradio.app/docs/chatinterface
-"""
-chatbot = gr.ChatInterface(
-    respond,
-    additional_inputs=[
-        gr.Textbox(value="You are a friendly Chatbot.", label="System message"),
-        gr.Slider(minimum=1, maximum=2048, value=512, step=1, label="Max new tokens"),
-        gr.Slider(minimum=0.1, maximum=4.0, value=0.7, step=0.1, label="Temperature"),
-        gr.Slider(
-            minimum=0.1,
-            maximum=1.0,
-            value=0.95,
-            step=0.05,
-            label="Top-p (nucleus sampling)",
-        ),
-    ],
-)
-
-with gr.Blocks() as demo:
+
+import bot
+from ledger import get_ledger
+from agent import stream_response, execute
+
+logging_format = "%(asctime)s %(levelname)s %(name)s: %(message)s"
+import logging
+logging.basicConfig(level=logging.INFO, format=logging_format)
+
+ledger = get_ledger()
+threading.Thread(target=bot.start, args=(ledger,), daemon=True).start()
+
+
+# ── chat handler ──────────────────────────────────────────────────────────────
+
+def respond(message: str, history: list[dict], hf_token: gr.OAuthToken):
+    token = hf_token.token if hf_token else os.getenv("HF_TOKEN", "")
+    if not token:
+        yield "Please log in with HuggingFace to use the assistant."
+        return
+
+    final_reply, final_action = "", None
+    for partial, action in stream_response(message, history, ledger, token):
+        final_reply, final_action = partial, action
+        yield partial
+
+    if final_action:
+        confirmation = execute(final_action, ledger, message)
+        if confirmation:
+            yield final_reply + "\n\n" + confirmation
+
+
+# ── ledger tab helpers ────────────────────────────────────────────────────────
+
+def refresh_ledger():
+    return ledger.recent(50), f"### 💰 Total: ${ledger.total():.2f}"
+
+
+# ── layout ────────────────────────────────────────────────────────────────────
+
+with gr.Blocks(theme=gr.themes.Soft(), title="💸 Finance Manager") as demo:
     with gr.Sidebar():
         gr.LoginButton()
-    chatbot.render()
+        gr.Markdown(f"**Storage:** {ledger.status}")
+
+    with gr.Tabs():
+        with gr.Tab("💬 Chat"):
+            gr.ChatInterface(
+                respond,
+                type="messages",
+                placeholder="e.g. 'Spent $12 on lunch' or 'How much did I spend on food?'",
+            )
+
+        with gr.Tab("📊 Ledger"):
+            refresh_btn = gr.Button("🔄 Refresh", variant="secondary")
+            table = gr.Dataframe(value=ledger.recent(50), interactive=False)
+            total_md = gr.Markdown(f"### 💰 Total: ${ledger.total():.2f}")
+            refresh_btn.click(fn=refresh_ledger, outputs=[table, total_md])
 
 
 if __name__ == "__main__":

bot.py

@@ -0,0 +1,111 @@
+"""Telegram bot — runs as a daemon thread sharing the same ledger instance."""
+
+import os
+import asyncio
+import logging
+import threading
+from telegram import Update
+from telegram.ext import (
+    ApplicationBuilder, CommandHandler, MessageHandler,
+    ContextTypes, filters,
+)
+
+from ledger import Ledger
+from agent import batch_response, execute
+
+logger = logging.getLogger(__name__)
+
+MAX_HISTORY = 20  # messages (10 turns) kept per user
+
+
+# ── handlers ──────────────────────────────────────────────────────────────────
+
+async def on_start(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    await update.message.reply_text(
+        "👋 *Finance Manager*\n\n"
+        "Just tell me about your expenses naturally:\n"
+        "• _Spent $12 on lunch_\n"
+        "• _Paid $1200 rent yesterday_\n"
+        "• _Undo_ — removes the last entry\n\n"
+        "Commands:\n"
+        "/summary — spending by category\n"
+        "/clear — reset conversation history",
+        parse_mode="Markdown",
+    )
+
+
+async def on_summary(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    ledger: Ledger = context.bot_data["ledger"]
+    by_cat = ledger.by_category()
+    total = ledger.total()
+
+    if not by_cat:
+        await update.message.reply_text("No entries yet. Start logging expenses!")
+        return
+
+    lines = [f"💰 *Total: ${total:.2f}*\n"]
+    lines += [
+        f"• {cat}: ${amt:.2f}"
+        for cat, amt in sorted(by_cat.items(), key=lambda x: -x[1])
+    ]
+    await update.message.reply_text("\n".join(lines), parse_mode="Markdown")
+
+
+async def on_clear(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    context.user_data["history"] = []
+    await update.message.reply_text("Conversation history cleared.")
+
+
+async def on_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    ledger: Ledger = context.bot_data["ledger"]
+    token = os.getenv("HF_TOKEN", "")
+
+    if not token:
+        await update.message.reply_text("HF_TOKEN is not configured.")
+        return
+
+    history: list[dict] = context.user_data.get("history", [])
+    text = update.message.text
+
+    reply, action = await asyncio.to_thread(batch_response, text, history, ledger, token)
+
+    if action:
+        confirmation = execute(action, ledger, text)
+        if confirmation:
+            reply += f"\n\n{confirmation}"
+
+    # Persist last N messages for context
+    context.user_data["history"] = (
+        history + [
+            {"role": "user", "content": text},
+            {"role": "assistant", "content": reply},
+        ]
+    )[-MAX_HISTORY:]
+
+    await update.message.reply_text(reply, parse_mode="Markdown")
+
+
+# ── entry point ───────────────────────────────────────────────────────────────
+
+def start(ledger: Ledger):
+    """Start the Telegram bot in a daemon thread. No-op if token not set."""
+    bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
+    if not bot_token:
+        logger.info("TELEGRAM_BOT_TOKEN not set — Telegram bot disabled.")
+        return
+
+    async def _run():
+        app = ApplicationBuilder().token(bot_token).build()
+        app.bot_data["ledger"] = ledger
+        app.add_handler(CommandHandler("start", on_start))
+        app.add_handler(CommandHandler("summary", on_summary))
+        app.add_handler(CommandHandler("clear", on_clear))
+        app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, on_message))
+
+        logger.info("Telegram bot polling started.")
+        async with app:
+            await app.start()
+            await app.updater.start_polling()
+            await asyncio.Event().wait()  # run until process exits
+
+    threading.Thread(target=lambda: asyncio.run(_run()), daemon=True).start()

ledger.py

@@ -0,0 +1,137 @@
+"""Thread-safe expense ledger with HuggingFace Hub CSV persistence."""
+
+import os
+import logging
+import threading
+import pandas as pd
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+COLUMNS = ["Date", "Description", "Category", "Amount"]
+CSV_NAME = "ledger.csv"
+CACHE_PATH = Path("/tmp/finance_ledger.csv")
+
+
+class Ledger:
+    def __init__(self):
+        self._lock = threading.RLock()
+        self.token = os.getenv("HF_TOKEN")
+        self.repo = os.getenv("HF_LEDGER_REPO")
+        self.enabled = bool(self.token and self.repo)
+        self.df = self._load()
+
+    # ── persistence ──────────────────────────────────────────────────────────
+
+    def _load(self) -> pd.DataFrame:
+        if self.enabled:
+            try:
+                self._ensure_repo()
+                from huggingface_hub import hf_hub_download
+                path = hf_hub_download(
+                    self.repo, CSV_NAME, repo_type="dataset",
+                    token=self.token, local_dir="/tmp",
+                )
+                return self._read_csv(path)
+            except Exception as e:
+                logger.warning(f"HF load failed ({e}), falling back to local cache")
+
+        if CACHE_PATH.exists():
+            try:
+                return self._read_csv(CACHE_PATH)
+            except Exception as e:
+                logger.warning(f"Local cache load failed: {e}")
+
+        return pd.DataFrame(columns=COLUMNS)
+
+    def _read_csv(self, path) -> pd.DataFrame:
+        df = pd.read_csv(path)
+        df["Date"] = pd.to_datetime(df["Date"])
+        df["Amount"] = pd.to_numeric(df["Amount"])
+        return df.sort_values("Date", ascending=False).reset_index(drop=True)
+
+    def _ensure_repo(self):
+        from huggingface_hub import repo_exists, create_repo
+        if not repo_exists(self.repo, repo_type="dataset", token=self.token):
+            create_repo(self.repo, repo_type="dataset", private=True,
+                        token=self.token, exist_ok=True)
+
+    def _persist(self):
+        df_copy = self.df.copy()
+        if not df_copy.empty:
+            df_copy["Date"] = df_copy["Date"].dt.strftime("%Y-%m-%d")
+        df_copy.to_csv(CACHE_PATH, index=False)
+
+        if not self.enabled:
+            return
+        try:
+            from huggingface_hub import upload_file
+            upload_file(
+                path_or_fileobj=str(CACHE_PATH),
+                path_in_repo=CSV_NAME,
+                repo_id=self.repo,
+                repo_type="dataset",
+                token=self.token,
+                commit_message="ledger update",
+            )
+        except Exception as e:
+            logger.error(f"HF upload failed: {e}")
+
+    # ── mutations ─────────────────────────────────────────────────────────────
+
+    def add(self, date: str, description: str, category: str, amount: float) -> bool:
+        with self._lock:
+            try:
+                row = pd.DataFrame({
+                    "Date": [pd.to_datetime(date)],
+                    "Description": [description],
+                    "Category": [category],
+                    "Amount": [float(amount)],
+                })
+                self.df = pd.concat([self.df, row], ignore_index=True)
+                self.df = self.df.sort_values("Date", ascending=False).reset_index(drop=True)
+                self._persist()
+                return True
+            except Exception as e:
+                logger.error(f"add failed: {e}")
+                return False
+
+    def delete_last(self) -> bool:
+        with self._lock:
+            if self.df.empty:
+                return False
+            self.df = self.df.iloc[1:].reset_index(drop=True)
+            self._persist()
+            return True
+
+    # ── queries ───────────────────────────────────────────────────────────────
+
+    def total(self) -> float:
+        return float(self.df["Amount"].sum()) if not self.df.empty else 0.0
+
+    def by_category(self) -> dict[str, float]:
+        if self.df.empty:
+            return {}
+        return self.df.groupby("Category")["Amount"].sum().to_dict()
+
+    def recent(self, n: int = 50) -> pd.DataFrame:
+        df = self.df.head(n).copy()
+        if not df.empty:
+            df["Date"] = df["Date"].dt.strftime("%Y-%m-%d")
+        return df
+
+    @property
+    def status(self) -> str:
+        return f"✅ HF Hub: `{self.repo}`" if self.enabled else "⚠️ Local cache only"
+
+
+# ── singleton ─────────────────────────────────────────────────────────────────
+
+_instance: Ledger | None = None
+
+
+def get_ledger() -> Ledger:
+    global _instance
+    if _instance is None:
+        _instance = Ledger()
+    return _instance

requirements.txt

@@ -0,0 +1,4 @@
+huggingface-hub>=0.20.0
+pandas>=2.0.0
+python-telegram-bot>=20.0
+python-dotenv>=1.0.0