fleece-cli 0.3.1__tar.gz → 0.4.0__tar.gz

fleece_cli-0.4.0/.claude/skills/fleece-profile.md

@@ -0,0 +1,81 @@
+---
+name: fleece-profile
+description: Manage the user's spending profile — monthly spend by category, annual fee tolerance, points programs, home airport, and redemption goal. Profile context is automatically injected into fleece wallet, fleece roi, and fleece recommend. Use when setting up or updating the user's preferences.
+---
+
+# /fleece-profile
+
+Manages the user's persistent spending profile stored in `fleece.db`. Once set, profile context is automatically injected into `fleece wallet`, `fleece roi`, and `fleece recommend` — no need to re-enter spend amounts each time.
+
+## When to use
+- User wants to set up their profile so research commands are personalised
+- User updates their spending habits or preferences
+- User asks why recommendations don't match their situation (profile may be empty or stale)
+- Before running `fleece recommend` or `fleece roi` for the first time
+
+## Profile fields
+
+| Field | Description |
+|---|---|
+| `dining_monthly` | Monthly dining spend ($) |
+| `groceries_monthly` | Monthly groceries spend ($) |
+| `travel_monthly` | Monthly travel spend ($) |
+| `gas_monthly` | Monthly gas spend ($) |
+| `other_monthly` | Monthly other spend ($) |
+| `annual_fee_tolerance` | Max annual fee willing to pay ($) |
+| `points_programs` | Preferred points programs (e.g. Amex MR, Chase UR) |
+| `home_airport` | Home airport IATA code (e.g. JFK) |
+| `goal` | Current redemption goal (e.g. business class to Tokyo) |
+| `preferences` | Other preferences (e.g. no foreign transaction fees) |
+
+## Usage
+
+```bash
+# See all available fields
+fleece profile fields
+
+# Show current profile
+fleece profile show
+fleece profile show --json
+
+# Set fields
+fleece profile set dining_monthly 600
+fleece profile set travel_monthly 300
+fleece profile set annual_fee_tolerance 550
+fleece profile set points_programs "Amex MR, Chase UR"
+fleece profile set home_airport JFK
+fleece profile set goal "business class to Tokyo, June 2027"
+
+# Clear a field
+fleece profile unset goal
+```
+
+## How profile enriches other commands
+
+Once set, you don't need to pass spend amounts manually:
+
+```bash
+# Without profile: must pass all spend flags
+fleece roi "Amex Gold" --dining 600 --travel 300 --other 800
+
+# With profile set: spend values pulled automatically
+fleece roi "Amex Gold"
+
+# fleece wallet and fleece recommend also use profile context automatically
+fleece wallet
+fleece recommend "travel rewards"
+```
+
+## Setup workflow
+
+```bash
+fleece profile set dining_monthly 600
+fleece profile set groceries_monthly 400
+fleece profile set travel_monthly 300
+fleece profile set gas_monthly 150
+fleece profile set other_monthly 800
+fleece profile set annual_fee_tolerance 250
+fleece profile set home_airport JFK
+fleece profile set goal "Fly business to Tokyo in 2027"
+fleece profile show
+```

{fleece_cli-0.3.1 → fleece_cli-0.4.0}/.github/workflows/publish.yml

@@ -5,6 +5,9 @@ on:
     tags:
       - "v*"
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   build:
     runs-on: ubuntu-latest

fleece_cli-0.4.0/CLAUDE.md

@@ -0,0 +1,123 @@
+# Fleece — Credit Card Research & Redemption
+
+## Project Overview
+
+**Fleece** is a credit card research and award redemption toolkit. Tagline: "Find the best card for deal saviors."
+
+It has two surfaces:
+1. **Streamlit chatbot** (`fleece.py`) — conversational AI assistant backed by OpenAI
+2. **CLI** (`cli.py`) — 12 commands for card research, wallet analysis, MCC lookup, and award redemption
+
+Published on PyPI as [`fleece-cli`](https://pypi.org/project/fleece-cli/) · current version **0.3.1**
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Chatbot frontend | Streamlit |
+| Chatbot LLM | OpenAI (gpt-3.5-turbo, gpt-4, gpt-4o) via LangChain |
+| Chatbot memory | ConversationEntityMemory |
+| CLI framework | Typer |
+| Live research | Brave Search API |
+| Card portfolio | SQLite (`fleece.db`) via `db.py` |
+| MCC dataset | Bundled `mcc_codes.jsonl` (981 codes, offline) |
+| Redemption URLs | `pointsyeah.py` (pure stdlib, no deps) |
+| Language | Python 3.11+ |
+
+---
+
+## CLI Commands
+
+### Research (requires `BRAVE_API_KEY`)
+| Command | Description |
+|---|---|
+| `fleece card "<name>"` | Full card report — fees, welcome offer, rates, credits, benefits |
+| `fleece rates "<name>"` | Earning rates by spend category |
+| `fleece partners "<name>"` | Transfer partners, ratios, timing |
+| `fleece credits "<name>"` | Statement credits and perks |
+| `fleece news "<name>"` | Recent changes (past month, freshness-filtered) |
+| `fleece compare "<A>" "<B>"` | Side-by-side comparison |
+| `fleece wallet` | Portfolio analysis — coverage, overlaps, gaps, next-card suggestions |
+| `fleece roi "<name>"` | First-year ROI estimate by spend profile |
+| `fleece recommend "<profile>"` | Card recommendations for a spending profile |
+
+### Redemption (no API key needed — work fully offline)
+| Command | Description |
+|---|---|
+| `fleece mcc <code>` | Offline MCC code lookup (981 codes bundled). Add `--wallet` to cross-reference saved cards |
+| `fleece flights <ORIGIN> <DEST> --date <YYYY-MM-DD>` | PointsYeah award flight search URL |
+| `fleece hotels "<location>" --checkin <date> --checkout <date>` | PointsYeah award hotel search URL |
+
+All commands support `--json` for agent-friendly output and `-` to read arguments from stdin.
+
+### BRAVE_API_KEY
+Optional at startup — checked only when a research command actually runs. `mcc`, `flights`, and `hotels` work with no key set.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `cli.py` | Main CLI entry point (Typer app) |
+| `fleece.py` | Streamlit chatbot app |
+| `db.py` | SQLite helpers for card portfolio (`fleece.db`) |
+| `pointsyeah.py` | PointsYeah URL generation (pure stdlib, merged from archived `pointsyeah-cli`) |
+| `mcc_codes.jsonl` | Bundled MCC dataset (981 codes, source: greggles/mcc-codes) |
+| `tools/brave_client.py` | Brave Search API client |
+| `tools/credit_card_tools.py` | LangChain tools for the chatbot |
+| `pyproject.toml` | Package config — hatchling build, `fleece` entry point |
+| `install.sh` | Installs Claude Code skills and/or agent skill |
+
+---
+
+## Agent Skills
+
+### Claude Code (`/.claude/skills/`)
+12 slash commands installed via `bash install.sh --claude`:
+
+**Research:** `/fleece-card` `/fleece-rates` `/fleece-partners` `/fleece-credits` `/fleece-news` `/fleece-compare` `/fleece-wallet` `/fleece-roi` `/fleece-recommend`
+
+**Redemption:** `/fleece-mcc` `/fleece-flights` `/fleece-hotels`
+
+### ClawHub / OpenClaw (`/.agents/skills/fleece/SKILL.md`)
+Published on ClawHub as `fleece@1.3.0`. Install via `clawhub install fleece` or `bash install.sh --agents`.
+
+---
+
+## CI/CD
+
+| Workflow | Trigger | Action |
+|---|---|---|
+| `publish.yml` | Push `v*` tag | Build and publish to PyPI via OIDC trusted publishing |
+| `publish-skills.yml` | Push to `main` touching `.agents/skills/` or `.claude/skills/` | Publish to ClawHub via `CLAWHUB_TOKEN` secret |
+
+GitHub environment `pypi` is required for the PyPI workflow (OIDC).
+
+---
+
+## Landing Page
+
+`docs/` is served as GitHub Pages at **https://getfleece.io/**.
+
+Contains `index.html`, `sitemap.xml`, `robots.txt`. Submitted to Google Search Console. JSON-LD structured data included.
+
+SEO notes tracked in `docs/SEO.md`.
+
+---
+
+## Infrastructure Notes
+
+- **Databricks**: No resources available. Do not suggest Databricks solutions until provisioned.
+- **pointsyeah-cli**: Archived. All functionality merged into fleece (`pointsyeah.py`, `fleece flights`, `fleece hotels`).
+
+---
+
+## Development Notes
+
+- Author: Yuan Chen
+- Created: March 16, 2025
+- Chatbot uses custom CSS styling (`style.css`)
+- OpenAI API key entered via Streamlit sidebar — not stored

{fleece_cli-0.3.1 → fleece_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleece-cli
-Version: 0.3.1
+Version: 0.4.0
 Summary: Credit card research and redemption CLI — live data via Brave Search, PointsYeah URL generation, designed for humans and AI agents.
 Author-email: Yuan Chen <cysbc1999@gmail.com>
 License: MIT

{fleece_cli-0.3.1 → fleece_cli-0.4.0}/cli.py

@@ -250,14 +250,18 @@ def wallet(
     except Exception as e:
         _error_exit(str(e), code=1)
 
+    import db as _db
+    profile_ctx = _db.profile_as_context()
+
     combined = "\n\n".join(parts)
-    combined += (
-        "\n\nBased on the above, identify:\n"
-        "1. Category coverage map\n"
-        "2. Overlapping benefits or redundant categories\n"
-        "3. Gaps — categories with no bonus multiplier\n"
-        "4. Top 1-2 cards that would complement this portfolio"
-    )
+    combined += "\n\nBased on the above, identify:\n"
+    combined += "1. Category coverage map\n"
+    combined += "2. Overlapping benefits or redundant categories\n"
+    combined += "3. Gaps — categories with no bonus multiplier\n"
+    combined += "4. Top 1-2 cards that would complement this portfolio"
+    if profile_ctx:
+        combined += f"\n\nUser profile context: {profile_ctx}"
+        combined += "\nTailor the gap analysis and recommendations to this profile."
     _emit(combined, as_json, "wallet", ", ".join(card_list))
 
 
@@ -274,10 +278,20 @@ def roi(
     """First-year ROI estimate — welcome bonus + earn + credits minus annual fee."""
     from tools.brave_client import search_and_format
     from tools.credit_card_tools import _guess_cpp
+    import db as _db
 
     name = _read_stdin_or_arg(name)
     key  = _resolve_key(api_key, no_dotenv)
 
+    # Pull spend values from saved profile if not provided on the command line
+    p = _db.get_profile()
+    if travel == 0.0 and p.get("travel_monthly"):
+        travel = float(p["travel_monthly"])
+    if dining == 0.0 and p.get("dining_monthly"):
+        dining = float(p["dining_monthly"])
+    if other  == 0.0 and p.get("other_monthly"):
+        other  = float(p["other_monthly"])
+
     annual_travel = travel * 12
     annual_dining = dining * 12
     annual_other  = other  * 12
@@ -310,10 +324,16 @@ def recommend(
     no_dotenv:   NoDotenv   = False,
 ):
     """Card recommendations matched to a spending profile and preferences."""
+    import db as _db
     profile = _read_stdin_or_arg(profile)
     key     = _resolve_key(api_key, no_dotenv)
     pref    = f"{preferences} " if preferences else ""
-    query   = f"best credit cards {profile} {pref}US 2025 site:nerdwallet.com OR site:thepointsguy.com OR site:doctorofcredit.com"
+
+    # Enrich with saved profile context if available
+    saved_ctx = _db.profile_as_context(cards=_db.get_card_names())
+    ctx = f"{saved_ctx} | " if saved_ctx else ""
+
+    query = f"best credit cards {ctx}{profile} {pref}US 2025 site:nerdwallet.com OR site:thepointsguy.com OR site:doctorofcredit.com"
     _run_search(_get_wrapper(key), query, "recommend", as_json)
 
 
@@ -465,6 +485,72 @@ def hotels(
         webbrowser.open(url)
 
 
+# ---------------------------------------------------------------------------
+# profile — spending profile management
+# ---------------------------------------------------------------------------
+
+profile_app = typer.Typer(name="profile", help="Manage your spending profile — used to personalise research commands.", no_args_is_help=True)
+app.add_typer(profile_app)
+
+
+@profile_app.command("show")
+def profile_show(as_json: JsonOpt = False):
+    """Show your current spending profile."""
+    import db as _db
+    p = _db.get_profile()
+    if not p:
+        typer.echo("No profile set. Run: fleece profile set <field> <value>")
+        typer.echo(f"Fields: {', '.join(_db.PROFILE_FIELDS)}")
+        return
+    if as_json:
+        typer.echo(json.dumps({"command": "profile show", "profile": p, "ok": True, "error": None}))
+        return
+    for key, label in _db.PROFILE_FIELDS.items():
+        val = p.get(key, "")
+        if val:
+            typer.echo(f"  {label:<45} {val}")
+
+
+@profile_app.command("set")
+def profile_set(
+    field: Annotated[str, typer.Argument(help=f"Field name. One of: {', '.join(__import__('db').PROFILE_FIELDS)}")],
+    value: Annotated[str, typer.Argument(help="Value to set.")],
+    as_json: JsonOpt = False,
+):
+    """Set a profile field."""
+    import db as _db
+    try:
+        _db.set_profile_field(field, value)
+    except ValueError as e:
+        _error_exit(str(e), code=1)
+    if as_json:
+        typer.echo(json.dumps({"command": "profile set", "field": field, "value": value, "ok": True, "error": None}))
+    else:
+        typer.echo(f"Profile updated: {field} = {value}")
+
+
+@profile_app.command("unset")
+def profile_unset(
+    field: Annotated[str, typer.Argument(help="Field name to clear.")],
+    as_json: JsonOpt = False,
+):
+    """Clear a single profile field."""
+    import db as _db
+    _db.clear_profile_field(field)
+    if as_json:
+        typer.echo(json.dumps({"command": "profile unset", "field": field, "ok": True, "error": None}))
+    else:
+        typer.echo(f"Cleared: {field}")
+
+
+@profile_app.command("fields")
+def profile_fields():
+    """List all available profile fields and their descriptions."""
+    import db as _db
+    for key, label in _db.PROFILE_FIELDS.items():
+        typer.echo(f"  {key:<30} {label}")
+
+
 # ---------------------------------------------------------------------------
 # cards — profile management (read/write user_cards.json)
 # ---------------------------------------------------------------------------

{fleece_cli-0.3.1 → fleece_cli-0.4.0}/db.py

@@ -23,8 +23,26 @@ CREATE TABLE IF NOT EXISTS cards (
     image_url    TEXT    NOT NULL DEFAULT '',
     date_added   TEXT    NOT NULL DEFAULT (date('now'))
 );
+CREATE TABLE IF NOT EXISTS profile (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL DEFAULT ''
+);
 """
 
+# Default profile fields and their human-readable labels
+PROFILE_FIELDS = {
+    "dining_monthly":        "Monthly dining spend ($)",
+    "groceries_monthly":     "Monthly groceries spend ($)",
+    "travel_monthly":        "Monthly travel spend ($)",
+    "gas_monthly":           "Monthly gas spend ($)",
+    "other_monthly":         "Monthly other spend ($)",
+    "annual_fee_tolerance":  "Max annual fee willing to pay ($)",
+    "points_programs":       "Preferred points programs (e.g. Amex MR, Chase UR)",
+    "home_airport":          "Home airport IATA code (e.g. JFK)",
+    "goal":                  "Current redemption goal (e.g. business class to Tokyo)",
+    "preferences":           "Other preferences (e.g. no foreign transaction fees)",
+}
+
 _COLUMNS = ("id", "name", "last_four", "annual_fee", "credit_limit",
             "rewards", "expiration", "image_url", "date_added")
 
@@ -133,6 +151,73 @@ def remove_card(name: str) -> bool:
     return cur.rowcount > 0
 
 
+# ---------------------------------------------------------------------------
+# Profile
+# ---------------------------------------------------------------------------
+
+def get_profile() -> dict[str, str]:
+    """Return the full profile as {key: value}. Missing keys return ''."""
+    init_db()
+    with _conn() as con:
+        rows = con.execute("SELECT key, value FROM profile").fetchall()
+    return {r["key"]: r["value"] for r in rows}
+
+
+def set_profile_field(key: str, value: str) -> None:
+    """Upsert a single profile field."""
+    if key not in PROFILE_FIELDS:
+        raise ValueError(f'Unknown profile field "{key}". Valid fields: {", ".join(PROFILE_FIELDS)}')
+    init_db()
+    with _conn() as con:
+        con.execute(
+            "INSERT INTO profile (key, value) VALUES (?, ?) "
+            "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            (key, value),
+        )
+
+
+def clear_profile_field(key: str) -> None:
+    """Remove a single profile field."""
+    init_db()
+    with _conn() as con:
+        con.execute("DELETE FROM profile WHERE key = ?", (key,))
+
+
+def profile_as_context(cards: list[str] | None = None) -> str:
+    """
+    Return a compact natural-language summary of the user profile suitable
+    for injecting into a Brave Search query or LLM prompt.
+    """
+    p = get_profile()
+    parts = []
+
+    spend_fields = [
+        ("dining_monthly", "dining"),
+        ("groceries_monthly", "groceries"),
+        ("travel_monthly", "travel"),
+        ("gas_monthly", "gas"),
+        ("other_monthly", "other"),
+    ]
+    spend_parts = [f"${p[k]}/mo {label}" for k, label in spend_fields if p.get(k)]
+    if spend_parts:
+        parts.append("Spending: " + ", ".join(spend_parts))
+
+    if p.get("annual_fee_tolerance"):
+        parts.append(f"Max annual fee: ${p['annual_fee_tolerance']}")
+    if p.get("points_programs"):
+        parts.append(f"Points programs: {p['points_programs']}")
+    if p.get("home_airport"):
+        parts.append(f"Home airport: {p['home_airport']}")
+    if p.get("goal"):
+        parts.append(f"Goal: {p['goal']}")
+    if p.get("preferences"):
+        parts.append(f"Preferences: {p['preferences']}")
+    if cards:
+        parts.append(f"Current cards: {', '.join(cards)}")
+
+    return " | ".join(parts) if parts else ""
+
+
 # ---------------------------------------------------------------------------
 # Migration
 # ---------------------------------------------------------------------------

{fleece_cli-0.3.1 → fleece_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fleece-cli"
-version = "0.3.1"
+version = "0.4.0"
 description = "Credit card research and redemption CLI — live data via Brave Search, PointsYeah URL generation, designed for humans and AI agents."
 readme = "README.md"
 license = { text = "MIT" }

fleece_cli-0.3.1/CLAUDE.md

@@ -1,49 +0,0 @@
-# Fleece - Credit Card Research Chatbot
-
-## Project Overview
-**Fleece** is a Streamlit-based conversational AI application designed to help users find the best credit cards for their needs. The tagline is "Find the best card for deal saviors."
-
-### Core Purpose
-Fleece is a chatbot that:
-- Uses OpenAI's chat models (gpt-3.5-turbo, gpt-4, gpt-4-turbo, gpt-4o) to provide conversational credit card research and recommendations
-- Maintains entity-based memory across conversations to remember user details and preferences
-- Allows users to explore available credit cards and manage their existing card portfolio
-- Stores conversation history and provides download capability
-
-### Tech Stack
-- **Frontend**: Streamlit (Python web app framework)
-- **LLM**: OpenAI ChatGPT (via LangChain)
-- **Memory**: ConversationEntityMemory (tracks entities mentioned in conversation)
-- **Language**: Python
-
-## Key Features
-1. **Conversational Interface**: Chat with an AI assistant about credit cards
-2. **Entity Memory**: Remembers details about the user across conversation turns
-3. **Multi-model Support**: Choose between different OpenAI models
-4. **Conversation Management**: 
-   - Start new chats
-   - Browse past conversation sessions
-   - Download conversation history
-   - Customize memory buffer size (K parameter)
-5. **Navigation**: Planned pages for "Credit Cards" exploration and "My Credit Cards" management
-
-## Current Limitations & Opportunities
-- **Limited knowledge**: Currently relies on OpenAI's training data, which may be outdated for credit card details
-- **No specialized tools**: The chatbot cannot search current issuer websites or real-time data sources
-- **No structured research**: Lacks the ability to provide specific, verified credit card information (fees, benefits, offers, transfer partners, etc.)
-
-## Future Integration Opportunities
-- **Multi-page app expansion**: Build out the "Credit Cards" discovery page and "My Credit Cards" portfolio management
-- **Database backend**: Store user profiles, card portfolios, and preferences
-
-## CLI — Redemption Commands
-The `fleece flights` and `fleece hotels` commands are merged from the former `pointsyeah-cli` project (now archived). They generate PointsYeah search URLs with no API key required — pure stdlib, zero external dependencies. Source lives in `pointsyeah.py`.
-
-## Development Notes
-- Author: Yuan Chen
-- Created: March 16, 2025
-- Uses custom CSS styling (style.css)
-- Requires OpenAI API key (entered via sidebar, not stored)
-
-## Infrastructure Notes
-- **Databricks**: No Databricks resources are available at the moment. The Databricks App deployment workflow has been removed. Do not suggest or implement Databricks-based solutions until resources are provisioned.