fleece-cli 0.1.0__py3-none-any.whl

cli.py

@@ -0,0 +1,391 @@
+"""
+Fleece CLI — agent-friendly companion to the Fleece Streamlit chatbot.
+
+Exposes credit card research tools as shell commands backed by Brave Search.
+Designed for use by AI agents (Claude Code, Codex) and humans alike.
+
+Exit codes:
+  0  success
+  1  search / tool error
+  2  configuration error (missing API key)
+"""
+import json
+import sys
+from typing import Annotated, Optional
+
+import typer
+from dotenv import load_dotenv
+
+app = typer.Typer(
+    name="fleece",
+    help="Fleece credit card research CLI — live data via Brave Search.",
+    no_args_is_help=True,
+)
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_key(api_key: Optional[str], no_dotenv: bool) -> str:
+    """Load env and return the Brave API key, or exit with code 2."""
+    import os
+    if not no_dotenv:
+        load_dotenv()
+    key = api_key or os.getenv("BRAVE_API_KEY", "")
+    if not key:
+        _error_exit(
+            "BRAVE_API_KEY not set. Pass --api-key or add it to .env.",
+            code=2,
+        )
+    return key
+
+
+def _get_wrapper(key: str, freshness: Optional[str] = None):
+    from tools.brave_client import build_brave_wrapper
+    return build_brave_wrapper(key, freshness=freshness)
+
+
+def _read_stdin_or_arg(value: str) -> str:
+    """If value is '-', read the first line from stdin."""
+    if value == "-":
+        return sys.stdin.readline().strip()
+    return value
+
+
+def _emit(result: str, as_json: bool, command: str, query: str) -> None:
+    if as_json:
+        typer.echo(json.dumps({"command": command, "query": query, "result": result, "ok": True, "error": None}))
+    else:
+        typer.echo(result)
+
+
+def _error_exit(message: str, code: int = 1) -> None:
+    typer.echo(
+        json.dumps({"ok": False, "error": message}),
+        err=True,
+    )
+    raise typer.Exit(code=code)
+
+
+def _run_search(wrapper, query: str, command: str, as_json: bool) -> None:
+    from tools.brave_client import search_and_format
+    try:
+        result = search_and_format(wrapper, query)
+        _emit(result, as_json, command, query)
+    except Exception as e:
+        _error_exit(str(e), code=1)
+
+
+# ---------------------------------------------------------------------------
+# User profile helpers (fleece.db)
+# ---------------------------------------------------------------------------
+
+def _load_profile() -> list[dict]:
+    import db
+    return db.get_cards()
+
+
+def _profile_card_names() -> list[str]:
+    import db
+    return db.get_card_names()
+
+
+# Reusable option annotations
+ApiKeyOpt     = Annotated[Optional[str], typer.Option("--api-key", help="Override BRAVE_API_KEY env var.")]
+JsonOpt       = Annotated[bool, typer.Option("--json", "-j", help="Emit JSON output (agent-friendly).")]
+NoDotenv      = Annotated[bool, typer.Option("--no-dotenv", help="Skip loading .env file.")]
+FromProfileOpt = Annotated[bool, typer.Option("--from-profile", "-p", help="Use cards saved in user_cards.json instead of passing names.")]
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+@app.command()
+def card(
+    name:      Annotated[str, typer.Argument(help="Card name. Use '-' to read from stdin.")],
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """Full card report — fees, welcome offer, earning rates, credits, benefits, strategy."""
+    name = _read_stdin_or_arg(name)
+    key  = _resolve_key(api_key, no_dotenv)
+    query = f'"{name}" credit card annual fee welcome offer earning rates benefits credits 2025'
+    _run_search(_get_wrapper(key), query, "card", as_json)
+
+
+@app.command()
+def rates(
+    name:      Annotated[str, typer.Argument(help="Card name. Use '-' to read from stdin.")],
+    category:  Annotated[Optional[str], typer.Option("--category", "-c", help="Spending category (dining, travel, groceries…)")] = None,
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """Earning rates by spend category — points, miles, or cash back per dollar."""
+    name = _read_stdin_or_arg(name)
+    key  = _resolve_key(api_key, no_dotenv)
+    cat  = f"{category} " if category else ""
+    query = f'"{name}" {cat}earning rates points miles cashback per dollar categories 2025'
+    _run_search(_get_wrapper(key), query, "rates", as_json)
+
+
+@app.command()
+def partners(
+    name:      Annotated[str, typer.Argument(help="Card name. Use '-' to read from stdin.")],
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """Transfer partners — airlines and hotels, ratios, and transfer timing."""
+    name = _read_stdin_or_arg(name)
+    key  = _resolve_key(api_key, no_dotenv)
+    query = f'"{name}" transfer partners airlines hotels ratio transfer time 2025'
+    _run_search(_get_wrapper(key), query, "partners", as_json)
+
+
+@app.command()
+def credits(
+    name:      Annotated[str, typer.Argument(help="Card name. Use '-' to read from stdin.")],
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """Statement credits and perks — amounts, cadence, and enrollment requirements."""
+    name = _read_stdin_or_arg(name)
+    key  = _resolve_key(api_key, no_dotenv)
+    query = f'"{name}" statement credits perks benefits complete list how to use 2025'
+    _run_search(_get_wrapper(key), query, "credits", as_json)
+
+
+@app.command()
+def news(
+    name:      Annotated[str, typer.Argument(help="Card name. Use '-' to read from stdin.")],
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """Recent changes in the past month — fee increases, benefit cuts, new perks."""
+    name = _read_stdin_or_arg(name)
+    key  = _resolve_key(api_key, no_dotenv)
+    query = f'"{name}" credit card changes update news 2025'
+    _run_search(_get_wrapper(key, freshness="pm"), query, "news", as_json)
+
+
+@app.command()
+def compare(
+    card_a:    Annotated[str, typer.Argument(help="First card name.")],
+    card_b:    Annotated[str, typer.Argument(help="Second card name.")],
+    aspects:   Annotated[str, typer.Option("--aspects", help="Comma-separated aspects to compare.")] = "fees,rewards,welcome_offer,credits,transfer_partners",
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """Side-by-side card comparison across fees, rewards, credits, and transfer partners."""
+    from tools.brave_client import search_and_format
+    key     = _resolve_key(api_key, no_dotenv)
+    wrapper = _get_wrapper(key)
+    asp     = aspects.replace(",", ", ")
+
+    try:
+        result_a = search_and_format(wrapper, f'"{card_a}" credit card {asp} 2025')
+        result_b = search_and_format(wrapper, f'"{card_b}" credit card {asp} 2025')
+        combined = f"## {card_a}\n{result_a}\n\n## {card_b}\n{result_b}"
+    except Exception as e:
+        _error_exit(str(e), code=1)
+        return
+    query    = f"{card_a} vs {card_b}"
+    _emit(combined, as_json, "compare", query)
+
+
+@app.command()
+def wallet(
+    cards:        Annotated[Optional[list[str]], typer.Argument(help="Card names (space-separated). Omit to use saved profile. Use '-' as sole arg to read from stdin.")] = None,
+    from_profile: FromProfileOpt = False,
+    api_key:      ApiKeyOpt  = None,
+    as_json:      JsonOpt    = False,
+    no_dotenv:    NoDotenv   = False,
+):
+    """Portfolio analysis — category coverage map, overlaps, gaps, and next-card suggestions.
+
+    Card names can come from three sources (in priority order):
+    1. Arguments passed directly
+    2. --from-profile / -p  (reads user_cards.json)
+    3. No args + saved profile exists (auto-loads profile)
+    """
+    from tools.brave_client import search_and_format
+
+    # Resolve card list
+    if cards and cards != ["-"]:
+        card_list = cards
+    elif cards == ["-"]:
+        card_list = [line.strip() for line in sys.stdin if line.strip()]
+    else:
+        # No args passed — fall back to saved profile
+        card_list = _profile_card_names()
+        if not card_list:
+            _error_exit(
+                "No cards provided and user_cards.json is empty. "
+                "Pass card names as arguments or add cards with: python cli.py cards add \"<name>\"",
+                code=1,
+            )
+
+    key     = _resolve_key(api_key, no_dotenv)
+    wrapper = _get_wrapper(key)
+    parts   = []
+
+    try:
+        for name in card_list:
+            result = search_and_format(wrapper, f'"{name}" earning rates categories benefits 2025', max_results=2)
+            parts.append(f"### {name}\n{result}")
+    except Exception as e:
+        _error_exit(str(e), code=1)
+
+    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"
+    )
+    _emit(combined, as_json, "wallet", ", ".join(card_list))
+
+
+@app.command()
+def roi(
+    name:      Annotated[str, typer.Argument(help="Card name. Use '-' to read from stdin.")],
+    travel:    Annotated[float, typer.Option("--travel",  help="Monthly travel spend ($).")] = 0.0,
+    dining:    Annotated[float, typer.Option("--dining",  help="Monthly dining spend ($).")] = 0.0,
+    other:     Annotated[float, typer.Option("--other",   help="Monthly other spend ($).")] = 0.0,
+    api_key:   ApiKeyOpt  = None,
+    as_json:   JsonOpt    = False,
+    no_dotenv: NoDotenv   = False,
+):
+    """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
+
+    name = _read_stdin_or_arg(name)
+    key  = _resolve_key(api_key, no_dotenv)
+
+    annual_travel = travel * 12
+    annual_dining = dining * 12
+    annual_other  = other  * 12
+    cpp = _guess_cpp(name)
+
+    try:
+        research = search_and_format(
+            _get_wrapper(key),
+            f'"{name}" annual fee welcome bonus points value first year 2025',
+        )
+        result = (
+            f"Annual spend — Travel: ${annual_travel:,.0f} | Dining: ${annual_dining:,.0f} | Other: ${annual_other:,.0f}\n"
+            f"Assumed value per point: {cpp}¢\n\n"
+            f"Live research:\n{research}\n\n"
+            "Calculate net first-year value: welcome bonus value + estimated annual earn + credits - annual fee. Show the math."
+        )
+    except Exception as e:
+        _error_exit(str(e), code=1)
+        return
+
+    _emit(result, as_json, "roi", name)
+
+
+@app.command()
+def recommend(
+    profile:     Annotated[str, typer.Argument(help="Spending profile description. Use '-' to read from stdin.")],
+    preferences: Annotated[Optional[str], typer.Option("--preferences", "-p", help="Extra preferences (e.g. 'no annual fee').")] = None,
+    api_key:     ApiKeyOpt  = None,
+    as_json:     JsonOpt    = False,
+    no_dotenv:   NoDotenv   = False,
+):
+    """Card recommendations matched to a spending profile and preferences."""
+    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"
+    _run_search(_get_wrapper(key), query, "recommend", as_json)
+
+
+# ---------------------------------------------------------------------------
+# cards — profile management (read/write user_cards.json)
+# ---------------------------------------------------------------------------
+
+cards_app = typer.Typer(name="cards", help="Manage your saved card profile (user_cards.json).", no_args_is_help=True)
+app.add_typer(cards_app)
+
+
+@cards_app.command("list")
+def cards_list(
+    as_json: JsonOpt = False,
+):
+    """List all cards saved in your profile."""
+    profile = _load_profile()
+    if not profile:
+        typer.echo("No cards in profile. Add one with: python cli.py cards add \"<card name>\"")
+        return
+    if as_json:
+        typer.echo(json.dumps({"command": "cards list", "cards": profile, "ok": True, "error": None}))
+    else:
+        for i, card in enumerate(profile, 1):
+            fee = card.get("annual_fee", "N/A")
+            typer.echo(f"{i}. {card['name']}  (fee: {fee})")
+
+
+@cards_app.command("add")
+def cards_add(
+    name:       Annotated[str, typer.Argument(help="Card name to add.")],
+    annual_fee: Annotated[str, typer.Option("--fee", help="Annual fee (e.g. $95).")] = "$0",
+    as_json:    JsonOpt = False,
+):
+    """Add a card to your profile."""
+    import datetime
+    import db
+    new_card = {
+        "name": name,
+        "annual_fee": annual_fee,
+        "date_added": datetime.date.today().isoformat(),
+    }
+    try:
+        db.add_card(new_card)
+    except ValueError as e:
+        _error_exit(str(e), code=1)
+    total = len(db.get_card_names())
+    if as_json:
+        typer.echo(json.dumps({"command": "cards add", "card": new_card, "ok": True, "error": None}))
+    else:
+        typer.echo(f'Added "{name}" to your profile. ({total} card(s) total)')
+
+
+@cards_app.command("remove")
+def cards_remove(
+    name:    Annotated[str, typer.Argument(help="Card name to remove (partial match OK).")],
+    as_json: JsonOpt = False,
+):
+    """Remove a card from your profile."""
+    import db
+    # Partial match against all names
+    all_cards = db.get_cards()
+    matches = [c for c in all_cards if name.lower() in c["name"].lower()]
+    if not matches:
+        _error_exit(f'No card matching "{name}" found in profile.', code=1)
+    if len(matches) > 1:
+        names = ", ".join(f'"{c["name"]}"' for c in matches)
+        _error_exit(f'Ambiguous match — found {names}. Be more specific.', code=1)
+    removed = matches[0]
+    db.remove_card(removed["name"])
+    remaining = len(db.get_card_names())
+    if as_json:
+        typer.echo(json.dumps({"command": "cards remove", "removed": removed["name"], "ok": True, "error": None}))
+    else:
+        typer.echo(f'Removed "{removed["name"]}" from your profile. ({remaining} card(s) remaining)')
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    app()

db.py

@@ -0,0 +1,162 @@
+"""
+SQLite persistence layer for Fleece user card profiles.
+
+Database file: fleece.db (project root, next to this file).
+Shared between the Streamlit UI and the CLI — both import this module directly.
+"""
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+DB_PATH = Path(__file__).parent / "fleece.db"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS cards (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    name         TEXT    NOT NULL UNIQUE,
+    last_four    TEXT    NOT NULL DEFAULT '',
+    annual_fee   TEXT    NOT NULL DEFAULT '$0',
+    credit_limit INTEGER NOT NULL DEFAULT 0,
+    rewards      TEXT    NOT NULL DEFAULT '',
+    expiration   TEXT    NOT NULL DEFAULT '',
+    image_url    TEXT    NOT NULL DEFAULT '',
+    date_added   TEXT    NOT NULL DEFAULT (date('now'))
+);
+"""
+
+_COLUMNS = ("id", "name", "last_four", "annual_fee", "credit_limit",
+            "rewards", "expiration", "image_url", "date_added")
+
+
+@contextmanager
+def _conn() -> Iterator[sqlite3.Connection]:
+    con = sqlite3.connect(DB_PATH)
+    con.row_factory = sqlite3.Row
+    try:
+        yield con
+        con.commit()
+    finally:
+        con.close()
+
+
+def init_db() -> None:
+    """Create tables if they don't exist. Safe to call on every startup."""
+    with _conn() as con:
+        con.executescript(_SCHEMA)
+
+
+def _row_to_dict(row: sqlite3.Row) -> dict:
+    return dict(row)
+
+
+# ---------------------------------------------------------------------------
+# Read
+# ---------------------------------------------------------------------------
+
+def get_cards() -> list[dict]:
+    """Return all cards ordered by date_added desc."""
+    init_db()
+    with _conn() as con:
+        rows = con.execute("SELECT * FROM cards ORDER BY date_added DESC").fetchall()
+    return [_row_to_dict(r) for r in rows]
+
+
+def get_card_names() -> list[str]:
+    """Return just the card names — used by the CLI wallet/roi commands."""
+    init_db()
+    with _conn() as con:
+        rows = con.execute("SELECT name FROM cards ORDER BY date_added DESC").fetchall()
+    return [r["name"] for r in rows]
+
+
+def get_card(name: str) -> dict | None:
+    """Return a single card by exact name, or None."""
+    init_db()
+    with _conn() as con:
+        row = con.execute("SELECT * FROM cards WHERE name = ?", (name,)).fetchone()
+    return _row_to_dict(row) if row else None
+
+
+# ---------------------------------------------------------------------------
+# Write
+# ---------------------------------------------------------------------------
+
+def add_card(card: dict) -> None:
+    """Insert a new card. Raises ValueError if name already exists."""
+    init_db()
+    with _conn() as con:
+        try:
+            con.execute(
+                """
+                INSERT INTO cards (name, last_four, annual_fee, credit_limit,
+                                   rewards, expiration, image_url, date_added)
+                VALUES (:name, :last_four, :annual_fee, :credit_limit,
+                        :rewards, :expiration, :image_url, :date_added)
+                """,
+                {
+                    "name":         card.get("name", ""),
+                    "last_four":    card.get("last_four", ""),
+                    "annual_fee":   card.get("annual_fee", "$0"),
+                    "credit_limit": card.get("credit_limit", 0),
+                    "rewards":      card.get("rewards", ""),
+                    "expiration":   card.get("expiration", ""),
+                    "image_url":    card.get("image_url", ""),
+                    "date_added":   card.get("date_added", ""),
+                },
+            )
+        except sqlite3.IntegrityError:
+            raise ValueError(f'Card "{card.get("name")}" already exists.')
+
+
+def update_card(name: str, updates: dict) -> bool:
+    """Update fields on an existing card. Returns True if found."""
+    if not updates:
+        return False
+    allowed = set(_COLUMNS) - {"id", "name", "date_added"}
+    fields = {k: v for k, v in updates.items() if k in allowed}
+    if not fields:
+        return False
+    init_db()
+    set_clause = ", ".join(f"{k} = :{k}" for k in fields)
+    fields["_name"] = name
+    with _conn() as con:
+        cur = con.execute(f"UPDATE cards SET {set_clause} WHERE name = :_name", fields)
+    return cur.rowcount > 0
+
+
+def remove_card(name: str) -> bool:
+    """Delete a card by exact name. Returns True if it existed."""
+    init_db()
+    with _conn() as con:
+        cur = con.execute("DELETE FROM cards WHERE name = ?", (name,))
+    return cur.rowcount > 0
+
+
+# ---------------------------------------------------------------------------
+# Migration
+# ---------------------------------------------------------------------------
+
+def migrate_from_json(json_path: Path) -> int:
+    """
+    Import cards from a JSON file into SQLite. Skips duplicates.
+    Returns the number of cards inserted.
+    """
+    import json
+
+    if not json_path.exists():
+        return 0
+
+    raw = json.loads(json_path.read_text())
+    if not isinstance(raw, list):
+        return 0
+
+    init_db()
+    inserted = 0
+    for card in raw:
+        try:
+            add_card(card)
+            inserted += 1
+        except ValueError:
+            pass  # already exists — skip
+    return inserted

fleece_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: fleece-cli
+Version: 0.1.0
+Summary: Credit card research CLI — live data via Brave Search, designed for humans and AI agents.
+Author-email: Yuan Chen <cysbc1999@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,brave-search,cli,credit-cards,finance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typer[all]>=0.12.0
+Description-Content-Type: text/markdown
+
+# Fleece - Credit Card Recommendation and Management App
+
+## Overview
+
+Fleece is a comprehensive credit card recommendation and management application built with Streamlit and LangChain. The app helps users find the best credit cards based on their spending habits and manage their existing credit card portfolio.
+
+## Author
+
+@chenyuan99
+
+## Features
+
+### Chat Interface
+- Interactive AI-powered chat assistant using OpenAI's GPT models
+- Conversation memory that remembers context across sessions
+- Entity memory to track important information mentioned in conversations
+- Ability to save and download conversation history
+
+### Credit Card Recommendations
+- Browse a curated list of popular credit cards with detailed information
+- Filter cards by annual fee, reward type, and other criteria
+- Get personalized card recommendations based on spending habits
+- Compare different cards side by side
+
+### My Credit Cards Management
+- Track all your existing credit cards in one place
+- Add new cards with templates or custom information
+- Edit card details and remove cards you no longer use
+- View portfolio insights with visualizations of credit limits and annual fees
+- Sort and filter your cards by various criteria
+
+## Performance Optimizations
+
+The application includes several performance optimizations:
+
+1. **Image Handling**
+   - Parallel image loading with ThreadPoolExecutor
+   - Multi-level image caching to reduce network requests
+   - Pre-generated default card images
+
+2. **Data Management**
+   - Streamlit caching with TTL for expensive operations
+   - Lazy loading of UI components
+   - Optimized data structures
+
+3. **UI/UX Improvements**
+   - Pagination for card displays
+   - Progressive loading with "Load More" buttons
+   - Form submission to reduce rerendering
+
+## Technical Architecture
+
+### Core Components
+- **fleece.py**: Main application entry point with chat interface
+- **pages/credit_cards.py**: Credit card recommendation page
+- **pages/my_credit_cards.py**: Personal credit card management page
+- **image_service.py**: Optimized image loading and caching service
+- **style.css**: Custom styling for the application
+
+### Dependencies
+- Streamlit: Web application framework
+- LangChain: Framework for working with language models
+- OpenAI: API for accessing GPT models
+- Pandas: Data manipulation and analysis
+- PIL: Image processing
+- Requests: HTTP requests for fetching card images
+
+## Installation and Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/chenyuan99/fleece.git
+   cd fleece
+   ```
+
+2. Create and activate a virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Set up your OpenAI API key in a `.env` file:
+   ```
+   OPENAI_API_KEY=your_api_key_here
+   ```
+
+5. Run the application:
+   ```bash
+   streamlit run fleece.py
+   ```
+
+## Usage Guide
+
+### Chat Interface
+- Enter your query in the text input field
+- The AI assistant will respond based on the conversation context
+- Use the "New Chat" button to start a fresh conversation
+- Download your conversation history using the download button
+
+### Credit Card Recommendations
+- Browse available credit cards in the expandable card views
+- Use sidebar filters to narrow down card options
+- Enter your spending habits in the form to get personalized recommendations
+- Click "Apply" on any card to start the application process
+
+### My Credit Cards
+- View all your cards with detailed information
+- Use the "Add New Card" tab to add a new credit card
+- Choose from templates or create a custom card entry
+- Edit or remove existing cards as needed
+- View portfolio insights to understand your credit profile
+
+## Resources
+
+- [OpenAI](https://openai.com/)
+- [LangChain](https://langchain.readthedocs.io/)
+- [Streamlit](https://streamlit.io/)
+
+## License
+
+MIT
+

fleece_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cli.py,sha256=6H1jaAH2-GUXSNBd3sRfkmq488PCeDI5xxGOf3sQmeE,14635
+db.py,sha256=x-oQYlCdZbyIupWhPGHgM9ZjRXkZ5RFIA1uI9YNHlok,5264
+tools/__init__.py,sha256=Bv38s7NE-dZbJt-FsatsiWDQZbFNcGygdaxK6rtFCqA,75
+tools/brave_client.py,sha256=kY4bOIzBZ-Ms0_qxC10q98XJKpq4zpiRYdr_Y5cG9Wg,2087
+tools/credit_card_tools.py,sha256=Zxbq_3IT268b5qIm-D54xhvsuRYJyllr3SFHxrq-tjU,11279
+fleece_cli-0.1.0.dist-info/METADATA,sha256=voWV4ueBzSjpl9LDDxScPwgM8rfGGr6Qv3IjoqubTIQ,4834
+fleece_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fleece_cli-0.1.0.dist-info/entry_points.txt,sha256=Lfg5NUmgv1I4rEQ8-0_Pvw1Zil6jJCQPzBd1NLIy3XI,35
+fleece_cli-0.1.0.dist-info/licenses/LICENSE,sha256=O-5w9AgSe9tlcKUD8TeZ7iPvQAlc8nRY3l8bDCLc8qo,1066
+fleece_cli-0.1.0.dist-info/RECORD,,

fleece_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fleece_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fleece = cli:app

fleece_cli-0.1.0.dist-info/licenses/LICENSE

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

tools/__init__.py

@@ -0,0 +1,3 @@
+from tools.credit_card_tools import build_tools
+
+__all__ = ["build_tools"]

tools/brave_client.py

@@ -0,0 +1,69 @@
+import os
+from pydantic import SecretStr
+
+PRIORITY_SITES = [
+    "chase.com",
+    "americanexpress.com",
+    "citi.com",
+    "capitalone.com",
+    "bankofamerica.com",
+    "wellsfargo.com",
+    "discover.com",
+    "barclays.com",
+    "biltrewards.com",
+    "nerdwallet.com",
+    "thepointsguy.com",
+    "doctorofcredit.com",
+    "bankrate.com",
+    "onemileatatime.com",
+]
+
+
+def build_brave_wrapper(api_key: str, freshness: str | None = None, count: int = 5):
+    from langchain_community.utilities import BraveSearchWrapper
+
+    search_kwargs: dict = {"count": count}
+    if freshness:
+        search_kwargs["freshness"] = freshness
+
+    return BraveSearchWrapper(
+        api_key=SecretStr(api_key),
+        search_kwargs=search_kwargs,
+    )
+
+
+def rerank_results(results: list[dict]) -> list[dict]:
+    def priority(r: dict) -> int:
+        url = r.get("link", r.get("url", ""))
+        for i, domain in enumerate(PRIORITY_SITES):
+            if domain in url:
+                return i
+        return len(PRIORITY_SITES)
+
+    return sorted(results, key=priority)
+
+
+def format_results_for_llm(results: list[dict], max_results: int = 4) -> str:
+    lines = []
+    for r in results[:max_results]:
+        title = r.get("title", "No title")
+        source = r.get("link", r.get("url", "Unknown source"))
+        snippet = r.get("snippet", r.get("description", ""))
+        if len(snippet) > 300:
+            snippet = snippet[:297] + "..."
+        lines.append(f"{title} | {source} | {snippet}")
+    return "\n".join(lines) if lines else "No results found."
+
+
+def search_and_format(wrapper, query: str, max_results: int = 4) -> str:
+    """Run a Brave search and return LLM-ready formatted results.
+
+    Falls back gracefully: tries _search() for structured reranking,
+    falls back to run() string output if _search() is unavailable.
+    """
+    try:
+        raw: list[dict] = wrapper._search(query)
+        reranked = rerank_results(raw)
+        return format_results_for_llm(reranked, max_results=max_results)
+    except (AttributeError, Exception):
+        return wrapper.run(query)

tools/credit_card_tools.py

@@ -0,0 +1,261 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+from langchain_core.tools import tool, BaseTool, StructuredTool
+
+from tools.brave_client import build_brave_wrapper, search_and_format
+
+# Cents-per-point defaults by issuer keyword for ROI calculation
+_CPP_MAP = {
+    "chase": 1.5,
+    "sapphire": 1.5,
+    "freedom": 1.0,
+    "amex": 1.8,
+    "american express": 1.8,
+    "gold": 1.8,
+    "platinum": 1.8,
+    "capital one": 1.35,
+    "venture": 1.35,
+    "citi": 1.6,
+    "strata": 1.6,
+    "bilt": 1.7,
+    "marriott": 0.8,
+    "hilton": 0.5,
+    "delta": 1.1,
+    "united": 1.2,
+    "southwest": 1.5,
+}
+
+
+def _guess_cpp(card_name: str) -> float:
+    lower = card_name.lower()
+    for keyword, cpp in _CPP_MAP.items():
+        if keyword in lower:
+            return cpp
+    return 1.0  # default to cash back value
+
+
+# ---------------------------------------------------------------------------
+# Pydantic schemas for multi-argument tools
+# ---------------------------------------------------------------------------
+
+class CompareCardsInput(BaseModel):
+    card_a: str = Field(description="Name of the first credit card")
+    card_b: str = Field(description="Name of the second credit card")
+    comparison_aspects: str = Field(
+        default="fees,rewards,welcome_offer,credits,transfer_partners",
+        description="Comma-separated aspects to compare",
+    )
+
+
+class FirstYearROIInput(BaseModel):
+    card_name: str = Field(description="Name of the credit card")
+    monthly_spend_travel: float = Field(default=0, description="Monthly travel spend in dollars")
+    monthly_spend_dining: float = Field(default=0, description="Monthly dining spend in dollars")
+    monthly_spend_other: float = Field(default=0, description="Monthly other spend in dollars")
+
+
+class AnalyzeWalletInput(BaseModel):
+    cards_owned: str = Field(description="Comma-separated list of credit cards the user currently holds")
+
+
+class RecommendCardsInput(BaseModel):
+    spending_profile: str = Field(description="Description of the user's spending habits and priorities")
+    preferences: str = Field(default="", description="Additional preferences (e.g. no annual fee, travel perks)")
+
+
+# ---------------------------------------------------------------------------
+# Tool factory
+# ---------------------------------------------------------------------------
+
+def build_tools(brave_api_key: str) -> list[BaseTool]:
+    wrapper = build_brave_wrapper(brave_api_key)
+    recent_wrapper = build_brave_wrapper(brave_api_key, freshness="pm")
+
+    # --- Tool 1: Full card report ---
+    @tool
+    def search_card_full_report(card_name: str) -> str:
+        """Look up a comprehensive credit card report including annual fee, welcome offer,
+        earning rates, statement credits, benefits, and redemption strategy.
+        Use when the user asks about a specific card in detail."""
+        query = f'"{card_name}" credit card annual fee welcome offer earning rates benefits credits 2025'
+        return search_and_format(wrapper, query)
+
+    # --- Tool 2: Earning rates ---
+    @tool
+    def search_card_earning_rates(card_name: str, category: str = "") -> str:
+        """Find the earning rates for a credit card, optionally filtered to a spending category
+        (dining, travel, groceries, gas, etc.).
+        Use when the user asks how many points, miles, or cash back a card earns."""
+        category_clause = f"{category} " if category else ""
+        query = f'"{card_name}" {category_clause}earning rates points miles cashback per dollar categories 2025'
+        return search_and_format(wrapper, query)
+
+    # --- Tool 3: Transfer partners ---
+    @tool
+    def search_transfer_partners(card_name: str) -> str:
+        """Find the airline and hotel transfer partners for a credit card's rewards program,
+        including transfer ratios and timing.
+        Use when the user asks about transfer partners or moving points to airlines/hotels."""
+        query = f'"{card_name}" transfer partners airlines hotels ratio transfer time 2025'
+        return search_and_format(wrapper, query)
+
+    # --- Tool 4: Statement credits ---
+    @tool
+    def search_statement_credits(card_name: str) -> str:
+        """Look up all statement credits and perks a credit card offers — dining, travel,
+        streaming, hotel, airline credits — including enrollment requirements.
+        Use when the user asks about credits, perks, or offsetting the annual fee."""
+        query = f'"{card_name}" statement credits perks benefits complete list how to use 2025'
+        return search_and_format(wrapper, query)
+
+    # --- Tool 5: First-year ROI ---
+    def _calculate_first_year_roi(
+        card_name: str,
+        monthly_spend_travel: float = 0,
+        monthly_spend_dining: float = 0,
+        monthly_spend_other: float = 0,
+    ) -> str:
+        """Calculate the estimated first-year return on investment for a credit card given
+        the user's spending habits.
+        Use when the user wants to know if a card is worth it based on how they spend."""
+        annual_travel = monthly_spend_travel * 12
+        annual_dining = monthly_spend_dining * 12
+        annual_other = monthly_spend_other * 12
+
+        query = f'"{card_name}" annual fee welcome bonus points value first year 2025'
+        research = search_and_format(wrapper, query)
+
+        cpp = _guess_cpp(card_name)
+        spend_summary = (
+            f"Annual spend — Travel: ${annual_travel:,.0f} | "
+            f"Dining: ${annual_dining:,.0f} | "
+            f"Other: ${annual_other:,.0f}\n"
+            f"Assumed value per point: {cpp}¢\n\n"
+            f"Live research results:\n{research}\n\n"
+            "Based on the research above, calculate the net first-year value as: "
+            "welcome bonus value + estimated annual earn value + annual credits - annual fee. "
+            "Show the math step by step."
+        )
+        return spend_summary
+
+    calculate_first_year_roi = StructuredTool.from_function(
+        func=_calculate_first_year_roi,
+        name="calculate_first_year_roi",
+        description=(
+            "Calculate the estimated first-year return on investment for a credit card "
+            "given the user's monthly spending on travel, dining, and other categories. "
+            "Use when the user wants to know if a card is worth it for them."
+        ),
+        args_schema=FirstYearROIInput,
+    )
+
+    # --- Tool 6: Compare two cards ---
+    def _compare_cards(
+        card_a: str,
+        card_b: str,
+        comparison_aspects: str = "fees,rewards,welcome_offer,credits,transfer_partners",
+    ) -> str:
+        """Compare two credit cards side by side across fees, rewards, welcome offers,
+        credits, and transfer partners.
+        Use when the user asks 'which is better' or wants to compare two specific cards."""
+        aspects = comparison_aspects.replace(",", ", ")
+        query_a = f'"{card_a}" credit card {aspects} 2025'
+        query_b = f'"{card_b}" credit card {aspects} 2025'
+        results_a = search_and_format(wrapper, query_a)
+        results_b = search_and_format(wrapper, query_b)
+        return (
+            f"## {card_a}\n{results_a}\n\n"
+            f"## {card_b}\n{results_b}\n\n"
+            "Compare the two cards above across these aspects and present a side-by-side "
+            f"markdown table: {aspects}."
+        )
+
+    compare_cards = StructuredTool.from_function(
+        func=_compare_cards,
+        name="compare_cards",
+        description=(
+            "Compare two credit cards side by side. Searches for current data on both cards "
+            "and produces a structured comparison. Use when the user asks 'which is better' "
+            "or wants to compare two specific cards."
+        ),
+        args_schema=CompareCardsInput,
+    )
+
+    # --- Tool 7: Wallet / portfolio analysis ---
+    def _analyze_wallet(cards_owned: str) -> str:
+        """Analyze the user's existing credit card portfolio for gaps, overlaps, and
+        optimization opportunities.
+        Use when the user says 'I have X and Y cards, how do I maximize?' or asks about their wallet."""
+        card_list = [c.strip() for c in cards_owned.split(",") if c.strip()]
+        results = []
+        for card in card_list:
+            query = f'"{card}" earning rates categories benefits 2025'
+            result = search_and_format(wrapper, query, max_results=2)
+            results.append(f"### {card}\n{result}")
+
+        combined = "\n\n".join(results)
+        return (
+            f"{combined}\n\n"
+            "Based on the card details above, identify:\n"
+            "1. Category coverage map (which card to use for travel, dining, groceries, gas, etc.)\n"
+            "2. Overlapping benefits or redundant earning categories\n"
+            "3. Gaps — spending categories with no bonus multiplier\n"
+            "4. Top 1-2 cards that would complement this portfolio"
+        )
+
+    analyze_wallet = StructuredTool.from_function(
+        func=_analyze_wallet,
+        name="analyze_wallet",
+        description=(
+            "Analyze the user's existing credit card portfolio for gaps, overlaps, and "
+            "optimization opportunities. Use when the user says 'I have X and Y cards, "
+            "how do I maximize?' or asks about their wallet/portfolio."
+        ),
+        args_schema=AnalyzeWalletInput,
+    )
+
+    # --- Tool 8: Recent news / changes ---
+    @tool
+    def search_recent_changes(card_name: str) -> str:
+        """Search for recent news and changes to a credit card in the last month —
+        benefit cuts, fee increases, new perks, or limited-time offers.
+        Use when the user asks if anything has changed recently about a card."""
+        query = f'"{card_name}" credit card changes update news 2025'
+        return search_and_format(recent_wrapper, query)
+
+    # --- Tool 9: Profile-based recommendations ---
+    def _recommend_cards_for_profile(
+        spending_profile: str,
+        preferences: str = "",
+    ) -> str:
+        """Search for the best US credit cards matching a spending profile and preferences.
+        Use when the user asks for card recommendations based on how they spend."""
+        pref_clause = f"{preferences} " if preferences else ""
+        query = (
+            f"best credit cards {spending_profile} {pref_clause}US 2025 "
+            f"site:nerdwallet.com OR site:thepointsguy.com OR site:doctorofcredit.com"
+        )
+        return search_and_format(wrapper, query)
+
+    recommend_cards_for_profile = StructuredTool.from_function(
+        func=_recommend_cards_for_profile,
+        name="recommend_cards_for_profile",
+        description=(
+            "Search for the best US credit cards matching a spending profile and preferences "
+            "(e.g. 'high dining and travel spend, no annual fee preferred'). "
+            "Use when the user asks for card recommendations based on their habits."
+        ),
+        args_schema=RecommendCardsInput,
+    )
+
+    return [
+        search_card_full_report,
+        search_card_earning_rates,
+        search_transfer_partners,
+        search_statement_credits,
+        calculate_first_year_roi,
+        compare_cards,
+        analyze_wallet,
+        search_recent_changes,
+        recommend_cards_for_profile,
+    ]