Deploy updated app and community contributions

.gitattributes

@@ -34,3 +34,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 products_vectorstore/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text
+_hf_capstone_repo/products_vectorstore/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text
+_hf_deploy/products_vectorstore/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text
+community_contributions/images/gui.png filter=lfs diff=lfs merge=lfs -text
+community_contributions/images/metrics.png filter=lfs diff=lfs merge=lfs -text
+space_staging/products_vectorstore/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text

_hf_capstone_repo/.gitattributes

@@ -0,0 +1,2 @@
+*.pth filter=lfs diff=lfs merge=lfs -text
+products_vectorstore/** filter=lfs diff=lfs merge=lfs -text

_hf_capstone_repo/README.md

@@ -0,0 +1,21 @@
+---
+title: Capstone - The Price Is Right
+emoji: 💰
+colorFrom: blue
+colorTo: green
+sdk: gradio
+sdk_version: "5.47.2"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Capstone — The Price Is Right
+
+Multi-agent deal hunting AI for the LLM Engineering capstone project.
+
+- Scans DealNews RSS feeds for deals
+- Estimates true product prices with RAG + Groq + neural network
+- Surfaces bargains in a live Gradio dashboard
+
+**Secrets required:** `GROQ_API_KEY`, `HF_TOKEN`, `USE_MODAL_SPECIALIST=false`, `GRADIO_SERVER_NAME=0.0.0.0`

_hf_capstone_repo/agents/agent.py

@@ -0,0 +1,33 @@
+import logging
+
+class Agent:
+    """
+    An abstract superclass for Agents
+    Used to log messages in a way that can identify each Agent
+    """
+
+    # Foreground colors
+    RED = '\033[31m'
+    GREEN = '\033[32m'
+    YELLOW = '\033[33m'
+    BLUE = '\033[34m'
+    MAGENTA = '\033[35m'
+    CYAN = '\033[36m'
+    WHITE = '\033[37m'
+    
+    # Background color
+    BG_BLACK = '\033[40m'
+    
+    # Reset code to return to default color
+    RESET = '\033[0m'
+
+    name: str = ""
+    color: str = '\033[37m'
+
+    def log(self, message):
+        """
+        Log this as an info message, identifying the agent
+        """
+        color_code = self.BG_BLACK + self.color
+        message = f"[{self.name}] {message}"
+        logging.info(color_code + message + self.RESET)

_hf_capstone_repo/agents/autonomous_planning_agent.py

@@ -0,0 +1,181 @@
+from typing import Optional, List, Dict
+from agents.agent import Agent
+from agents.deals import Deal, Opportunity
+from agents.scanner_agent import ScannerAgent
+from agents.ensemble_agent import EnsembleAgent
+from agents.messaging_agent import MessagingAgent
+from openai import OpenAI
+import json
+
+
+class AutonomousPlanningAgent(Agent):
+    name = "Autonomous Planning Agent"
+    color = Agent.GREEN
+    MODEL = "gpt-5.1"
+
+    def __init__(self, collection):
+        """
+        Create instances of the 3 Agents that this planner coordinates across
+        """
+        self.log("Autonomous Planning Agent is initializing")
+        self.scanner = ScannerAgent()
+        self.ensemble = EnsembleAgent(collection)
+        self.messenger = MessagingAgent()
+        self.openai = OpenAI()
+        self.memory = None
+        self.opportunity = None
+        self.log("Autonomous Planning Agent is ready")
+
+    def scan_the_internet_for_bargains(self) -> str:
+        """
+        Run the tool to scan
+        """
+        self.log("Autonomous Planning agent is calling scanner")
+        results = self.scanner.scan(memory=self.memory)
+        return results.model_dump_json() if results else "No deals found"
+
+    def estimate_true_value(self, description: str) -> str:
+        """
+        Run the tool to estimate true value
+        """
+        self.log("Autonomous Planning agent is estimating value via Ensemble Agent")
+        estimate = self.ensemble.price(description)
+        return f"The estimated true value of {description} is {estimate}"
+
+    def notify_user_of_deal(
+        self, description: str, deal_price: float, estimated_true_value: float, url: str
+    ) -> Dict:
+        """
+        Run the tool to notify the user
+        """
+        if self.opportunity:
+            self.log("Autonomous Planning agent is trying to notify the user a 2nd time; ignoring")
+        else:
+            self.log("Autonomous Planning agent is notifying user")
+            self.messenger.notify(description, deal_price, estimated_true_value, url)
+            deal = Deal(product_description=description, price=deal_price, url=url)
+            discount = estimated_true_value - deal_price
+            self.opportunity = Opportunity(
+                deal=deal, estimate=estimated_true_value, discount=discount
+            )
+        return "Notification sent ok"
+
+    scan_function = {
+        "name": "scan_the_internet_for_bargains",
+        "description": "Returns top bargains scraped from the internet along with the price each item is being offered for",
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+            "additionalProperties": False,
+        },
+    }
+
+    estimate_function = {
+        "name": "estimate_true_value",
+        "description": "Given the description of an item, estimate how much it is actually worth",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "The description of the item to be estimated",
+                },
+            },
+            "required": ["description"],
+            "additionalProperties": False,
+        },
+    }
+
+    notify_function = {
+        "name": "notify_user_of_deal",
+        "description": "Send the user a push notification about the single most compelling deal; only call this one time",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "The description of the item itself scraped from the internet",
+                },
+                "deal_price": {
+                    "type": "number",
+                    "description": "The price offered by this deal scraped from the internet",
+                },
+                "estimated_true_value": {
+                    "type": "number",
+                    "description": "The estimated actual value that this is worth",
+                },
+                "url": {
+                    "type": "string",
+                    "description": "The URL of this deal as scraped from the internet",
+                },
+            },
+            "required": ["description", "deal_price", "estimated_true_value", "url"],
+            "additionalProperties": False,
+        },
+    }
+
+    def get_tools(self):
+        """
+        Return the json for the tools to be used
+        """
+        return [
+            {"type": "function", "function": self.scan_function},
+            {"type": "function", "function": self.estimate_function},
+            {"type": "function", "function": self.notify_function},
+        ]
+
+    def handle_tool_call(self, message):
+        """
+        Actually call the tools associated with this message
+        """
+        mapping = {
+            "scan_the_internet_for_bargains": self.scan_the_internet_for_bargains,
+            "estimate_true_value": self.estimate_true_value,
+            "notify_user_of_deal": self.notify_user_of_deal,
+        }
+        results = []
+        for tool_call in message.tool_calls:
+            tool_name = tool_call.function.name
+            arguments = json.loads(tool_call.function.arguments)
+            tool = mapping.get(tool_name)
+            result = tool(**arguments) if tool else ""
+            results.append({"role": "tool", "content": result, "tool_call_id": tool_call.id})
+        return results
+
+    system_message = "You find great deals on bargain products using your tools, and notify the user of the best bargain."
+    user_message = """
+    First, use your tool to scan the internet for bargain deals. Then for each deal, use your tool to estimate its true value.
+    Then pick the single most compelling deal where the price is much lower than the estimated true value, and use your tool to notify the user.
+    Then just reply OK to indicate success.
+    """
+    messages = [
+        {"role": "system", "content": system_message},
+        {"role": "user", "content": user_message},
+    ]
+
+    def plan(self, memory: List[str] = []) -> Optional[Opportunity]:
+        """
+        Run the full workflow, providing the LLM with tools to surface scraped deals to the user
+        :param memory: a list of URLs that have been surfaced in the past
+        :return: an Opportunity if one was surfaced, otherwise None
+        """
+        self.log("Autonomous Planning Agent is kicking off a run")
+        self.memory = memory
+        self.opportunity = None
+        messages = self.messages[:]
+        done = False
+        while not done:
+            response = self.openai.chat.completions.create(
+                model=self.MODEL, messages=messages, tools=self.get_tools()
+            )
+            if response.choices[0].finish_reason == "tool_calls":
+                message = response.choices[0].message
+                results = self.handle_tool_call(message)
+                messages.append(message)
+                messages.extend(results)
+            else:
+                done = True
+        reply = response.choices[0].message.content
+        self.log(f"Autonomous Planning Agent completed with: {reply}")
+        return self.opportunity

_hf_capstone_repo/agents/deals.py

@@ -0,0 +1,134 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Self
+from bs4 import BeautifulSoup
+import re
+import feedparser
+from tqdm import tqdm
+import requests
+import time
+
+feeds = [
+    "https://www.dealnews.com/c142/Electronics/?rss=1",
+    "https://www.dealnews.com/c39/Computers/?rss=1",
+    "https://www.dealnews.com/f1912/Smart-Home/?rss=1",
+]
+
+# You could also add: "https://www.dealnews.com/c238/Automotive/?rss=1"
+# "https://www.dealnews.com/c196/Home-Garden/?rss=1"
+
+
+def extract(html_snippet: str) -> str:
+    """
+    Use Beautiful Soup to clean up this HTML snippet and extract useful text
+    """
+    soup = BeautifulSoup(html_snippet, "html.parser")
+    snippet_div = soup.find("div", class_="snippet summary")
+
+    if snippet_div:
+        description = snippet_div.get_text(strip=True)
+        description = BeautifulSoup(description, "html.parser").get_text()
+        description = re.sub("<[^<]+?>", "", description)
+        result = description.strip()
+    else:
+        result = html_snippet
+    return result.replace("\n", " ")
+
+
+class ScrapedDeal:
+    """
+    A class to represent a Deal retrieved from an RSS feed
+    """
+
+    category: str
+    title: str
+    summary: str
+    url: str
+    details: str
+    features: str
+
+    def __init__(self, entry: Dict[str, str]):
+        """
+        Populate this instance based on the provided dict
+        """
+        self.title = entry["title"]
+        self.summary = extract(entry["summary"])
+        self.url = entry["links"][0]["href"]
+        stuff = requests.get(self.url).content
+        soup = BeautifulSoup(stuff, "html.parser")
+        content = soup.find("div", class_="content-section").get_text()
+        content = content.replace("\nmore", "").replace("\n", " ")
+        if "Features" in content:
+            self.details, self.features = content.split("Features", 1)
+        else:
+            self.details = content
+            self.features = ""
+        self.truncate()
+
+    def truncate(self):
+        """
+        Limit the fields to a sensible length to avoid sending too much info to the model
+        """
+        self.title = self.title[:100]
+        self.details = self.details[:500]
+        self.features = self.features[:500]
+
+    def __repr__(self):
+        """
+        Return a string to describe this deal
+        """
+        return f"<{self.title}>"
+
+    def describe(self):
+        """
+        Return a longer string to describe this deal for use in calling a model
+        """
+        return f"Title: {self.title}\nDetails: {self.details.strip()}\nFeatures: {self.features.strip()}\nURL: {self.url}"
+
+    @classmethod
+    def fetch(cls, show_progress: bool = False) -> List[Self]:
+        """
+        Retrieve all deals from the selected RSS feeds
+        """
+        deals = []
+        feed_iter = tqdm(feeds) if show_progress else feeds
+        for feed_url in feed_iter:
+            feed = feedparser.parse(feed_url)
+            for entry in feed.entries[:10]:
+                deals.append(cls(entry))
+                time.sleep(0.05)
+        return deals
+
+
+class Deal(BaseModel):
+    """
+    A class to Represent a Deal with a summary description
+    """
+
+    product_description: str = Field(
+        description="Your clearly expressed summary of the product in 3-4 sentences. Details of the item are much more important than why it's a good deal. Avoid mentioning discounts and coupons; focus on the item itself. There should be a short paragraph of text for each item you choose."
+    )
+    price: float = Field(
+        description="The actual price of this product, as advertised in the deal. Be sure to give the actual price; for example, if a deal is described as $100 off the usual $300 price, you should respond with $200"
+    )
+    url: str = Field(description="The URL of the deal, as provided in the input")
+
+
+class DealSelection(BaseModel):
+    """
+    A class to Represent a list of Deals
+    """
+
+    deals: List[Deal] = Field(
+        description="Your selection of the 5 deals that have the most detailed, high quality description and the most clear price. You should be confident that the price reflects the deal, that it is a good deal, with a clear description"
+    )
+
+
+class Opportunity(BaseModel):
+    """
+    A class to represent a possible opportunity: a Deal where we estimate
+    it should cost more than it's being offered
+    """
+
+    deal: Deal
+    estimate: float
+    discount: float

_hf_capstone_repo/agents/deep_neural_network.py

@@ -0,0 +1,101 @@
+import numpy as np
+from tqdm.notebook import tqdm
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, TensorDataset
+from torch.optim.lr_scheduler import CosineAnnealingLR
+from sklearn.feature_extraction.text import HashingVectorizer
+import logging
+
+
+class ResidualBlock(nn.Module):
+    def __init__(self, hidden_size, dropout_prob):
+        super(ResidualBlock, self).__init__()
+        self.block = nn.Sequential(
+            nn.Linear(hidden_size, hidden_size),
+            nn.LayerNorm(hidden_size),
+            nn.ReLU(),
+            nn.Dropout(dropout_prob),
+            nn.Linear(hidden_size, hidden_size),
+            nn.LayerNorm(hidden_size),
+        )
+        self.relu = nn.ReLU()
+
+    def forward(self, x):
+        residual = x
+        out = self.block(x)
+        out += residual  # Skip connection
+        return self.relu(out)
+
+
+class DeepNeuralNetwork(nn.Module):
+    def __init__(self, input_size, num_layers=10, hidden_size=4096, dropout_prob=0.2):
+        super(DeepNeuralNetwork, self).__init__()
+
+        # First layer
+        self.input_layer = nn.Sequential(
+            nn.Linear(input_size, hidden_size),
+            nn.LayerNorm(hidden_size),
+            nn.ReLU(),
+            nn.Dropout(dropout_prob),
+        )
+
+        # Residual blocks
+        self.residual_blocks = nn.ModuleList()
+        for i in range(num_layers - 2):
+            self.residual_blocks.append(ResidualBlock(hidden_size, dropout_prob))
+
+        # Output layer
+        self.output_layer = nn.Linear(hidden_size, 1)
+
+    def forward(self, x):
+        x = self.input_layer(x)
+
+        for block in self.residual_blocks:
+            x = block(x)
+
+        return self.output_layer(x)
+
+
+Y_STD = 1.0328539609909058
+Y_MEAN = 4.434937953948975
+
+
+class DeepNeuralNetworkInference:
+    def __init__(self):
+        self.vectorizer = None
+        self.model = None
+        self.device = None
+
+        np.random.seed(42)
+        torch.manual_seed(42)
+        torch.cuda.manual_seed(42)
+
+    def setup(self):
+        self.vectorizer = HashingVectorizer(n_features=5000, stop_words="english", binary=True)
+        self.model = DeepNeuralNetwork(5000)
+        if torch.cuda.is_available():
+            self.device = torch.device("cuda")
+        elif torch.backends.mps.is_available():
+            self.device = torch.device("mps")
+        else:
+            self.device = torch.device("cpu")
+
+        logging.info(f"Neural Network is using {self.device}")
+
+        self.model.to(self.device)
+
+    def load(self, path):
+        self.model.load_state_dict(torch.load(path, map_location=self.device))
+        self.model.to(self.device)
+
+    def inference(self, text):
+        self.model.eval()
+        with torch.no_grad():
+            vector = self.vectorizer.transform([text])
+            vector = torch.FloatTensor(vector.toarray()).to(self.device)
+            pred = self.model(vector)[0]
+            result = torch.exp(pred * Y_STD + Y_MEAN) - 1
+            result = result.item()
+        return max(0, result)

_hf_capstone_repo/agents/ensemble_agent.py

@@ -0,0 +1,51 @@
+from agents.agent import Agent
+from agents.specialist_agent import SpecialistAgent
+from agents.frontier_agent import FrontierAgent
+from agents.neural_network_agent import NeuralNetworkAgent
+from agents.preprocessor import Preprocessor
+from free_config import WEIGHTS_WITH_SPECIALIST, WEIGHTS_WITHOUT_SPECIALIST
+
+
+class EnsembleAgent(Agent):
+    name = "Ensemble Agent"
+    color = Agent.YELLOW
+
+    def __init__(self, collection):
+        """
+        Create an instance of Ensemble, by creating each of the models
+        And loading the weights of the Ensemble
+        """
+        self.log("Initializing Ensemble Agent")
+        self.specialist = SpecialistAgent()
+        self.frontier = FrontierAgent(collection)
+        self.neural_network = NeuralNetworkAgent()
+        self.preprocessor = Preprocessor()
+        self.use_specialist = self.specialist.available
+        if self.use_specialist:
+            mode = getattr(self.specialist, "mode", "on")
+            self.log(f"Ensemble Agent is ready (Frontier + Specialist [{mode}] + Neural Network)")
+        else:
+            self.log("Ensemble Agent is ready (Frontier + Neural Network only)")
+
+    def price(self, description: str) -> float:
+        """
+        Run this ensemble model
+        Ask each of the models to price the product
+        Then return the weighted average price
+        """
+        self.log("Running Ensemble Agent - preprocessing text")
+        rewrite = self.preprocessor.preprocess(description)
+        self.log(f"Pre-processed text using {self.preprocessor.model_name}")
+        frontier = self.frontier.price(rewrite)
+        neural_network = self.neural_network.price(rewrite)
+
+        if self.use_specialist:
+            specialist = self.specialist.price(rewrite)
+            wf, ws, wn = WEIGHTS_WITH_SPECIALIST
+            combined = frontier * wf + specialist * ws + neural_network * wn
+        else:
+            wf, wn = WEIGHTS_WITHOUT_SPECIALIST
+            combined = frontier * wf + neural_network * wn
+
+        self.log(f"Ensemble Agent complete - returning ${combined:.2f}")
+        return combined

_hf_capstone_repo/agents/evaluator.py

@@ -0,0 +1,218 @@
+import re
+from sklearn.metrics import mean_squared_error, r2_score
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+from itertools import accumulate
+import math
+from tqdm.notebook import tqdm
+from concurrent.futures import ThreadPoolExecutor
+
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+RED = "\033[91m"
+RESET = "\033[0m"
+COLOR_MAP = {"red": RED, "orange": YELLOW, "green": GREEN}
+
+WORKERS = 5
+DEFAULT_SIZE = 200
+
+
+class Tester:
+    def __init__(self, predictor, data, title=None, size=DEFAULT_SIZE, workers=WORKERS):
+        self.predictor = predictor
+        self.data = data
+        self.title = title or self.make_title(predictor)
+        self.size = size
+        self.titles = []
+        self.guesses = []
+        self.truths = []
+        self.errors = []
+        self.colors = []
+        self.workers = workers
+
+    @staticmethod
+    def make_title(predictor) -> str:
+        return predictor.__name__.replace("__", ".").replace("_", " ").title().replace("Gpt", "GPT")
+
+    @staticmethod
+    def post_process(value):
+        if isinstance(value, str):
+            value = value.replace("$", "").replace(",", "")
+            match = re.search(r"[-+]?\d*\.\d+|\d+", value)
+            return float(match.group()) if match else 0
+        else:
+            return value
+
+    def color_for(self, error, truth):
+        if error < 40 or error / truth < 0.2:
+            return "green"
+        elif error < 80 or error / truth < 0.4:
+            return "orange"
+        else:
+            return "red"
+
+    def run_datapoint(self, i):
+        datapoint = self.data[i]
+        value = self.predictor(datapoint)
+        guess = self.post_process(value)
+        truth = datapoint.price
+        error = abs(guess - truth)
+        color = self.color_for(error, truth)
+        title = datapoint.title if len(datapoint.title) <= 40 else datapoint.title[:40] + "..."
+        return title, guess, truth, error, color
+
+    def chart(self, title):
+        df = pd.DataFrame(
+            {
+                "truth": self.truths,
+                "guess": self.guesses,
+                "title": self.titles,
+                "error": self.errors,
+                "color": self.colors,
+            }
+        )
+
+        # Pre-format hover text
+        df["hover"] = [
+            f"{t}\nGuess=${g:,.2f} Actual=${y:,.2f}"
+            for t, g, y in zip(df["title"], df["guess"], df["truth"])
+        ]
+
+        max_val = float(max(df["truth"].max(), df["guess"].max()))
+
+        fig = px.scatter(
+            df,
+            x="truth",
+            y="guess",
+            color="color",
+            color_discrete_map={"green": "green", "orange": "orange", "red": "red"},
+            title=title,
+            labels={"truth": "Actual Price", "guess": "Predicted Price"},
+            width=1000,
+            height=800,
+        )
+
+        # Assign customdata per trace (one color/category = one trace)
+        for tr in fig.data:
+            mask = df["color"] == tr.name
+            tr.customdata = df.loc[mask, ["hover"]].to_numpy()
+            tr.hovertemplate = "%{customdata[0]}<extra></extra>"
+            tr.marker.update(size=6)
+
+        # Reference line y=x
+        fig.add_trace(
+            go.Scatter(
+                x=[0, max_val],
+                y=[0, max_val],
+                mode="lines",
+                line=dict(width=2, dash="dash", color="deepskyblue"),
+                name="y = x",
+                hoverinfo="skip",
+                showlegend=False,
+            )
+        )
+
+        fig.update_xaxes(range=[0, max_val])
+        fig.update_yaxes(range=[0, max_val])
+        fig.update_layout(showlegend=False)
+        fig.show()
+
+    def error_trend_chart(self):
+        n = len(self.errors)
+
+        # Running mean and std (pure Python)
+        running_sums = list(accumulate(self.errors))
+        x = list(range(1, n + 1))
+        running_means = [s / i for s, i in zip(running_sums, x)]
+
+        running_squares = list(accumulate(e * e for e in self.errors))
+        running_stds = [
+            math.sqrt((sq_sum / i) - (mean**2)) if i > 1 else 0
+            for i, sq_sum, mean in zip(x, running_squares, running_means)
+        ]
+
+        # 95% confidence interval for mean
+        ci = [1.96 * (sd / math.sqrt(i)) if i > 1 else 0 for i, sd in zip(x, running_stds)]
+        upper = [m + c for m, c in zip(running_means, ci)]
+        lower = [m - c for m, c in zip(running_means, ci)]
+
+        # Plot
+        fig = go.Figure()
+
+        # Shaded confidence interval band
+        fig.add_trace(
+            go.Scatter(
+                x=x + x[::-1],
+                y=upper + lower[::-1],
+                fill="toself",
+                fillcolor="rgba(128,128,128,0.2)",
+                line=dict(color="rgba(255,255,255,0)"),
+                hoverinfo="skip",
+                showlegend=False,
+                name="95% CI",
+            )
+        )
+
+        # Main line with hover text showing CI
+        fig.add_trace(
+            go.Scatter(
+                x=x,
+                y=running_means,
+                mode="lines",
+                line=dict(width=3, color="firebrick"),
+                name="Cumulative Avg Error",
+                customdata=list(
+                    zip(
+                        ci,
+                    )
+                ),
+                hovertemplate=(
+                    "n=%{x}<br>"
+                    "Avg Error=$%{y:,.2f}<br>"
+                    "±95% CI=$%{customdata[0]:,.2f}<extra></extra>"
+                ),
+            )
+        )
+
+        # Title with final stats
+        final_mean = running_means[-1]
+        final_ci = ci[-1]
+        title = f"{self.title} Error: ${final_mean:,.2f} ± ${final_ci:,.2f}"
+
+        fig.update_layout(
+            title=title,
+            xaxis_title="Number of Datapoints",
+            yaxis_title="Average Absolute Error ($)",
+            width=1000,
+            height=360,
+            template="plotly_white",
+            showlegend=False,
+        )
+
+        fig.show()
+
+    def report(self):
+        average_error = sum(self.errors) / self.size
+        mse = mean_squared_error(self.truths, self.guesses)
+        r2 = r2_score(self.truths, self.guesses) * 100
+        title = f"{self.title} results<br><b>Error:</b> ${average_error:,.2f} <b>MSE:</b> {mse:,.0f} <b>r²:</b> {r2:.1f}%"
+        self.error_trend_chart()
+        self.chart(title)
+
+    def run(self):
+        with ThreadPoolExecutor(max_workers=self.workers) as ex:
+            for title, guess, truth, error, color in tqdm(
+                ex.map(self.run_datapoint, range(self.size)), total=self.size
+            ):
+                self.titles.append(title)
+                self.guesses.append(guess)
+                self.truths.append(truth)
+                self.errors.append(error)
+                self.colors.append(color)
+                print(f"{COLOR_MAP[color]}${error:.0f} ", end="")
+        self.report()
+
+
+def evaluate(function, data, size=DEFAULT_SIZE, workers=WORKERS):
+    Tester(function, data, size=size, workers=workers).run()

_hf_capstone_repo/agents/frontier_agent.py

@@ -0,0 +1,86 @@
+import os
+import re
+from typing import List, Dict
+
+from groq import Groq
+from sentence_transformers import SentenceTransformer
+
+from agents.agent import Agent
+from free_config import GROQ_MODEL
+
+
+class FrontierAgent(Agent):
+    name = "Frontier Agent"
+    color = Agent.BLUE
+
+    def __init__(self, collection):
+        """
+        Set up this instance by connecting to Groq, the Chroma datastore,
+        and the local sentence-transformer embedding model.
+        """
+        self.log("Initializing Frontier Agent")
+        self.client = Groq(api_key=os.environ["GROQ_API_KEY"])
+        self.model = GROQ_MODEL
+        self.log(f"Frontier Agent is setting up with Groq ({self.model})")
+        self.collection = collection
+        self.encoder = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
+        self.log("Frontier Agent is ready")
+
+    def make_context(self, similars: List[str], prices: List[float]) -> str:
+        """
+        Create context that can be inserted into the prompt
+        """
+        message = "To provide some context, here are some other items that might be similar to the item you need to estimate.\n\n"
+        for similar, price in zip(similars, prices):
+            message += f"Potentially related product:\n{similar}\nPrice is ${price:.2f}\n\n"
+        return message
+
+    def messages_for(
+        self, description: str, similars: List[str], prices: List[float]
+    ) -> List[Dict[str, str]]:
+        """
+        Create the message list for the Groq chat completion call
+        """
+        message = f"Estimate the price of this product. Respond with the price only, no explanation.\n\n{description}\n\n"
+        message += self.make_context(similars, prices)
+        return [{"role": "user", "content": message}]
+
+    def find_similars(self, description: str):
+        """
+        Return a list of items similar to the given one by looking in the Chroma datastore
+        """
+        self.log(
+            "Frontier Agent is performing a RAG search of the Chroma datastore to find 5 similar products"
+        )
+        vector = self.encoder.encode([description])
+        results = self.collection.query(query_embeddings=vector.astype(float).tolist(), n_results=5)
+        documents = results["documents"][0][:]
+        prices = [m["price"] for m in results["metadatas"][0][:]]
+        self.log("Frontier Agent has found similar products")
+        return documents, prices
+
+    def get_price(self, s) -> float:
+        """
+        A utility that plucks a floating point number out of a string
+        """
+        s = s.replace("$", "").replace(",", "")
+        match = re.search(r"[-+]?\d*\.\d+|\d+", s)
+        return float(match.group()) if match else 0.0
+
+    def price(self, description: str) -> float:
+        """
+        Call Groq to estimate the price using RAG context from similar products.
+        """
+        documents, prices = self.find_similars(description)
+        self.log(
+            f"Frontier Agent is about to call Groq ({self.model}) with context including 5 similar products"
+        )
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=self.messages_for(description, documents, prices),
+            temperature=0,
+        )
+        reply = response.choices[0].message.content
+        result = self.get_price(reply)
+        self.log(f"Frontier Agent completed - predicting ${result:.2f}")
+        return result

_hf_capstone_repo/agents/items.py

@@ -0,0 +1,52 @@
+from pydantic import BaseModel
+from datasets import Dataset, DatasetDict, load_dataset
+from typing import Optional, Self
+
+
+PREFIX = "Price is $"
+QUESTION = "What does this cost to the nearest dollar?"
+
+
+class Item(BaseModel):
+    """
+    An Item is a data-point of a Product with a Price
+    """
+
+    title: str
+    category: str
+    price: float
+    full: Optional[str] = None
+    weight: Optional[float] = None
+    summary: Optional[str] = None
+    prompt: Optional[str] = None
+    id: Optional[int] = None
+
+    def make_prompt(self, text: str):
+        self.prompt = f"{QUESTION}\n\n{text}\n\n{PREFIX}{round(self.price)}.00"
+
+    def test_prompt(self) -> str:
+        return self.prompt.split(PREFIX)[0] + PREFIX
+
+    def __repr__(self) -> str:
+        return f"<{self.title} = ${self.price}>"
+
+    @staticmethod
+    def push_to_hub(dataset_name: str, train: list[Self], val: list[Self], test: list[Self]):
+        """Push Item lists to HuggingFace Hub"""
+        DatasetDict(
+            {
+                "train": Dataset.from_list([item.model_dump() for item in train]),
+                "validation": Dataset.from_list([item.model_dump() for item in val]),
+                "test": Dataset.from_list([item.model_dump() for item in test]),
+            }
+        ).push_to_hub(dataset_name)
+
+    @classmethod
+    def from_hub(cls, dataset_name: str) -> tuple[list[Self], list[Self], list[Self]]:
+        """Load from HuggingFace Hub and reconstruct Items"""
+        ds = load_dataset(dataset_name)
+        return (
+            [cls.model_validate(row) for row in ds["train"]],
+            [cls.model_validate(row) for row in ds["validation"]],
+            [cls.model_validate(row) for row in ds["test"]],
+        )

_hf_capstone_repo/agents/messaging_agent.py

@@ -0,0 +1,79 @@
+import os
+
+import requests
+from litellm import completion
+
+from agents.deals import Opportunity
+from agents.agent import Agent
+from free_config import MESSAGING_MODEL, PUSHOVER_CONFIGURED
+
+pushover_url = "https://api.pushover.net/1/messages.json"
+
+
+class MessagingAgent(Agent):
+    name = "Messaging Agent"
+    color = Agent.WHITE
+
+    def __init__(self):
+        """
+        Set up Pushover notifications (optional) and Groq for message crafting.
+        """
+        self.log("Messaging Agent is initializing")
+        self.pushover_user = os.getenv("PUSHOVER_USER", "")
+        self.pushover_token = os.getenv("PUSHOVER_TOKEN", "")
+        self.model = MESSAGING_MODEL
+        if PUSHOVER_CONFIGURED:
+            self.log("Messaging Agent has Pushover configured")
+        else:
+            self.log("Messaging Agent: Pushover not configured — alerts will be logged only")
+
+    def push(self, text):
+        """
+        Send a Push Notification using the Pushover API, or log if not configured.
+        """
+        if not PUSHOVER_CONFIGURED:
+            self.log(f"Deal alert (Pushover skipped): {text[:120]}...")
+            return
+        self.log("Messaging Agent is sending a push notification")
+        payload = {
+            "user": self.pushover_user,
+            "token": self.pushover_token,
+            "message": text,
+            "sound": "cashregister",
+        }
+        requests.post(pushover_url, data=payload)
+
+    def alert(self, opportunity: Opportunity):
+        """
+        Make an alert about the specified Opportunity
+        """
+        text = f"Deal Alert! Price=${opportunity.deal.price:.2f}, "
+        text += f"Estimate=${opportunity.estimate:.2f}, "
+        text += f"Discount=${opportunity.discount:.2f} :"
+        text += opportunity.deal.product_description[:10] + "... "
+        text += opportunity.deal.url
+        self.push(text)
+        self.log("Messaging Agent has completed")
+
+    def craft_message(
+        self, description: str, deal_price: float, estimated_true_value: float
+    ) -> str:
+        user_prompt = "Please summarize this great deal in 2-3 sentences to be sent as an exciting push notification alerting the user about this deal.\n"
+        user_prompt += f"Item Description: {description}\nOffered Price: {deal_price}\nEstimated true value: {estimated_true_value}"
+        user_prompt += "\n\nRespond only with the 2-3 sentence message which will be used to alert & excite the user about this deal"
+        response = completion(
+            model=self.model,
+            messages=[
+                {"role": "user", "content": user_prompt},
+            ],
+        )
+        return response.choices[0].message.content
+
+    def notify(self, description: str, deal_price: float, estimated_true_value: float, url: str):
+        """
+        Make an alert about the specified details
+        """
+        self.log(f"Messaging Agent is using Groq ({self.model}) to craft the message")
+        text = self.craft_message(description, deal_price, estimated_true_value)
+        self.push(text[:200] + "... " + url)
+        self.log("Messaging Agent has completed")

_hf_capstone_repo/agents/neural_network_agent.py

@@ -0,0 +1,29 @@
+from agents.agent import Agent
+from agents.deep_neural_network import DeepNeuralNetworkInference
+
+
+class NeuralNetworkAgent(Agent):
+    name = "Neural Network Agent"
+    color = Agent.MAGENTA
+
+    def __init__(self):
+        """
+        Initialize this object by loading in the saved model weights
+        and the SentenceTransformer vector encoding model
+        """
+        self.log("Neural Network Agent is initializing")
+        self.neural_network = DeepNeuralNetworkInference()
+        self.neural_network.setup()
+        self.neural_network.load("deep_neural_network.pth")
+        self.log("Neural Network Agent is ready and weights are loaded")
+
+    def price(self, description: str) -> float:
+        """
+        Use the Deep Neural Network to estimate the price of the described item
+        :param description: the product to be estimated
+        :return: the price as a float
+        """
+        self.log("Neural Network Agent is starting a prediction")
+        result = self.neural_network.inference(description)
+        self.log(f"Neural Network Agent completed - predicting ${result:.2f}")
+        return result

_hf_capstone_repo/agents/planning_agent.py

@@ -0,0 +1,57 @@
+from typing import Optional, List
+from agents.agent import Agent
+from agents.deals import ScrapedDeal, DealSelection, Deal, Opportunity
+from agents.scanner_agent import ScannerAgent
+from agents.ensemble_agent import EnsembleAgent
+from agents.messaging_agent import MessagingAgent
+
+
+class PlanningAgent(Agent):
+
+    name = "Planning Agent"
+    color = Agent.GREEN
+    DEAL_THRESHOLD = 50
+
+    def __init__(self, collection):
+        """
+        Create instances of the 3 Agents that this planner coordinates across
+        """
+        self.log("Planning Agent is initializing")
+        self.scanner = ScannerAgent()
+        self.ensemble = EnsembleAgent(collection)
+        self.messenger = MessagingAgent()
+        self.log("Planning Agent is ready")
+
+    def run(self, deal: Deal) -> Opportunity:
+        """
+        Run the workflow for a particular deal
+        :param deal: the deal, summarized from an RSS scrape
+        :returns: an opportunity including the discount
+        """
+        self.log("Planning Agent is pricing up a potential deal")
+        estimate = self.ensemble.price(deal.product_description)
+        discount = estimate - deal.price
+        self.log(f"Planning Agent has processed a deal with discount ${discount:.2f}")
+        return Opportunity(deal=deal, estimate=estimate, discount=discount)
+
+    def plan(self, memory: List[str] = []) -> Optional[Opportunity]:
+        """
+        Run the full workflow:
+        1. Use the ScannerAgent to find deals from RSS feeds
+        2. Use the EnsembleAgent to estimate them
+        3. Use the MessagingAgent to send a notification of deals
+        :param memory: a list of URLs that have been surfaced in the past
+        :return: an Opportunity if one was surfaced, otherwise None
+        """
+        self.log("Planning Agent is kicking off a run")
+        selection = self.scanner.scan(memory=memory)
+        if selection:
+            opportunities = [self.run(deal) for deal in selection.deals[:5]]
+            opportunities.sort(key=lambda opp: opp.discount, reverse=True)
+            best = opportunities[0]
+            self.log(f"Planning Agent has identified the best deal has discount ${best.discount:.2f}")
+            if best.discount > self.DEAL_THRESHOLD:
+                self.messenger.alert(best)
+            self.log("Planning Agent has completed a run")
+            return best if best.discount > self.DEAL_THRESHOLD else None
+        return None

_hf_capstone_repo/agents/preprocessor.py

@@ -0,0 +1,50 @@
+import os
+
+from dotenv import load_dotenv
+from litellm import completion
+
+from free_config import PREPROCESSOR_MODEL
+
+load_dotenv(override=True)
+
+DEFAULT_REASONING_EFFORT = "low" if "gpt-oss" in PREPROCESSOR_MODEL else None
+
+SYSTEM_PROMPT = """Create a concise description of a product. Respond only in this format. Do not include part numbers.
+Title: Rewritten short precise title
+Category: eg Electronics
+Brand: Brand name
+Description: 1 sentence description
+Details: 1 sentence on features"""
+
+
+class Preprocessor:
+    def __init__(
+        self,
+        model_name=PREPROCESSOR_MODEL,
+        reasoning_effort=DEFAULT_REASONING_EFFORT,
+        base_url=None,
+    ):
+        self.total_input_tokens = 0
+        self.total_output_tokens = 0
+        self.total_cost = 0
+        self.model_name = model_name
+        self.reasoning_effort = reasoning_effort
+        self.base_url = base_url
+        if "ollama" in model_name and not base_url:
+            self.base_url = "http://localhost:11434"
+
+    def messages_for(self, text: str) -> list[dict]:
+        return [{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": text}]
+
+    def preprocess(self, text: str) -> str:
+        messages = self.messages_for(text)
+        response = completion(
+            messages=messages,
+            model=self.model_name,
+            reasoning_effort=self.reasoning_effort,
+            api_base=self.base_url,
+        )
+        self.total_input_tokens += response.usage.prompt_tokens
+        self.total_output_tokens += response.usage.completion_tokens
+        self.total_cost += response._hidden_params["response_cost"]
+        return response.choices[0].message.content

_hf_capstone_repo/agents/scanner_agent.py

@@ -0,0 +1,176 @@
+import json
+import os
+import re
+from typing import Optional, List
+
+from groq import BadRequestError, Groq
+
+from agents.deals import ScrapedDeal, DealSelection
+from agents.agent import Agent
+from free_config import GROQ_MODEL
+
+
+class ScannerAgent(Agent):
+    MAX_DEALS_PER_REQUEST = 15
+
+    JSON_FORMAT_HINT = (
+        '\n\nRespond with JSON only, using this shape: '
+        '{"deals": [{"product_description": "...", "price": 99.99, "url": "https://..."}]}'
+        '\nThe JSON must be valid: no double-quote characters inside product_description '
+        '(write "6.9 inches" instead of 6.9"). No trailing commas. '
+        'Close the deals array with a single ] and the object with a single }.'
+    )
+
+    SYSTEM_PROMPT = """You identify and summarize the 5 most detailed deals from a list, by selecting deals that have the most detailed, high quality description and the most clear price.
+    You should provide the price as a number derived from the description. If the price of a deal isn't clear, do not include that deal in your response.
+    Most important is that you respond with the 5 deals that have the most detailed product description with price. It's not important to mention the terms of the deal; most important is a thorough description of the product.
+    Be careful with products that are described as "$XXX off" or "reduced by $XXX" - this isn't the actual price of the product. Only respond with products when you are highly confident about the price.
+    Never use the double-quote character inside product_description text. Spell out inch measurements as words, e.g. "55 inches" not 55".
+    """
+
+    USER_PROMPT_PREFIX = """Respond with the most promising 5 deals from this list, selecting those which have the most detailed, high quality product description and a clear price that is greater than 0.
+    You should rephrase the description to be a summary of the product itself, not the terms of the deal.
+    Remember to respond with a short paragraph of text in the product_description field for each of the 5 items that you select.
+    Be careful with products that are described as "$XXX off" or "reduced by $XXX" - this isn't the actual price of the product. Only respond with products when you are highly confident about the price.
+
+    Deals:
+
+    """
+
+    USER_PROMPT_SUFFIX = "\n\nInclude exactly 5 deals, no more."
+
+    name = "Scanner Agent"
+    color = Agent.CYAN
+
+    def __init__(self):
+        self.log("Scanner Agent is initializing")
+        self.client = Groq(api_key=os.environ["GROQ_API_KEY"])
+        self.model = GROQ_MODEL
+        self.log(f"Scanner Agent is ready (Groq / {self.model})")
+
+    def fetch_deals(self, memory) -> List[ScrapedDeal]:
+        """
+        Look up deals published on RSS feeds
+        Return any new deals that are not already in the memory provided
+        """
+        self.log("Scanner Agent is about to fetch deals from RSS feed")
+        urls = [opp.deal.url for opp in memory]
+        scraped = ScrapedDeal.fetch()
+        result = [scrape for scrape in scraped if scrape.url not in urls]
+        self.log(f"Scanner Agent received {len(result)} deals not already scraped")
+        return result
+
+    def make_user_prompt(self, scraped) -> str:
+        """
+        Create a user prompt based on the scraped deals provided
+        """
+        user_prompt = self.USER_PROMPT_PREFIX
+        user_prompt += "\n\n".join(
+            [scrape.describe() for scrape in scraped[: self.MAX_DEALS_PER_REQUEST]]
+        )
+        user_prompt += self.USER_PROMPT_SUFFIX
+        return user_prompt
+
+    @staticmethod
+    def _repair_deals_json(text: str) -> str:
+        text = text.strip()
+        text = re.sub(r'(\d+(?:\.\d+)?)"(\s+(?=[a-zA-Z0-9]))', r"\1 inches\2", text)
+        text = re.sub(r'("url"\s*:\s*"[^"]*")\s*\]', r"\1\n      }", text)
+        text = re.sub(
+            r'("url"\s*:\s*"[^"]*")\s*\}\s*\n\s*\]\s*\n\s*\}\}',
+            r"\1\n      }\n  ]\n}",
+            text,
+        )
+        text = re.sub(r"(\])\s*\]\s*\}\s*\}", r"\1}", text)
+        text = re.sub(r"(\])\s*\]\s*\}", r"\1}", text)
+        text = re.sub(r"\}\s*\}\s*$", r"}", text)
+        return text
+
+    def _parse_deals_json(self, content: str) -> DealSelection:
+        last_error = None
+        for candidate in (content, self._repair_deals_json(content)):
+            try:
+                result = DealSelection.model_validate(json.loads(candidate))
+                result.deals = [deal for deal in result.deals if deal.price > 0]
+                return result
+            except (json.JSONDecodeError, ValueError) as exc:
+                last_error = exc
+        raise ValueError(f"Could not parse deals JSON: {last_error}")
+
+    @staticmethod
+    def _extract_failed_generation(exc: BadRequestError) -> Optional[str]:
+        body = getattr(exc, "body", None)
+        if isinstance(body, dict):
+            return body.get("error", {}).get("failed_generation")
+        return None
+
+    def _call_groq(self, user_prompt: str) -> DealSelection:
+        messages = [
+            {"role": "system", "content": self.SYSTEM_PROMPT + self.JSON_FORMAT_HINT},
+            {"role": "user", "content": user_prompt},
+        ]
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                response_format={"type": "json_object"},
+                temperature=0,
+            )
+            return self._parse_deals_json(response.choices[0].message.content)
+        except BadRequestError as exc:
+            failed = self._extract_failed_generation(exc)
+            if failed:
+                self.log("Scanner Agent repairing malformed JSON from Groq response")
+                return self._parse_deals_json(failed)
+            raise
+
+    def scan(self, memory: List[str] = []) -> Optional[DealSelection]:
+        """
+        Call Groq to provide a high potential list of deals with good descriptions and prices
+        :param memory: a list of URLs representing deals already raised
+        :return: a selection of good deals, or None if there aren't any
+        """
+        scraped = self.fetch_deals(memory)
+        if not scraped:
+            return None
+        user_prompt = self.make_user_prompt(scraped)
+        self.log(f"Scanner Agent is calling Groq ({self.model})")
+        try:
+            result = self._call_groq(user_prompt)
+        except Exception as exc:
+            self.log(f"Scanner Agent failed to parse Groq response: {exc}")
+            return None
+        self.log(
+            f"Scanner Agent received {len(result.deals)} selected deals with price>0 from Groq"
+        )
+        return result
+
+    def test_scan(self, memory: List[str] = []) -> Optional[DealSelection]:
+        """
+        Return a test DealSelection, to be used during testing
+        """
+        results = {
+            "deals": [
+                {
+                    "product_description": "The Hisense R6 Series 55R6030N is a 55-inch 4K UHD Roku Smart TV that offers stunning picture quality with 3840x2160 resolution. It features Dolby Vision HDR and HDR10 compatibility, ensuring a vibrant and dynamic viewing experience. The TV runs on Roku's operating system, allowing easy access to streaming services and voice control compatibility with Google Assistant and Alexa. With three HDMI ports available, connecting multiple devices is simple and efficient.",
+                    "price": 178,
+                    "url": "https://www.dealnews.com/products/Hisense/Hisense-R6-Series-55-R6030-N-55-4-K-UHD-Roku-Smart-TV/484824.html?iref=rss-c142",
+                },
+                {
+                    "product_description": "The Poly Studio P21 is a 21.5-inch LED personal meeting display designed specifically for remote work and video conferencing. With a native resolution of 1080p, it provides crystal-clear video quality, featuring a privacy shutter and stereo speakers. This display includes a 1080p webcam with manual pan, tilt, and zoom control, along with an ambient light sensor to adjust the vanity lighting as needed. It also supports 5W wireless charging for mobile devices, making it an all-in-one solution for home offices.",
+                    "price": 30,
+                    "url": "https://www.dealnews.com/products/Poly-Studio-P21-21-5-1080-p-LED-Personal-Meeting-Display/378335.html?iref=rss-c39",
+                },
+                {
+                    "product_description": "The Lenovo IdeaPad Slim 5 laptop is powered by a 7th generation AMD Ryzen 5 8645HS 6-core CPU, offering efficient performance for multitasking and demanding applications. It features a 16-inch touch display with a resolution of 1920x1080, ensuring bright and vivid visuals. Accompanied by 16GB of RAM and a 512GB SSD, the laptop provides ample speed and storage for all your files. This model is designed to handle everyday tasks with ease while delivering an enjoyable user experience.",
+                    "price": 446,
+                    "url": "https://www.dealnews.com/products/Lenovo/Lenovo-Idea-Pad-Slim-5-7-th-Gen-Ryzen-5-16-Touch-Laptop/485068.html?iref=rss-c39",
+                },
+                {
+                    "product_description": "The Dell G15 gaming laptop is equipped with a 6th-generation AMD Ryzen 5 7640HS 6-Core CPU, providing powerful performance for gaming and content creation. It features a 15.6-inch 1080p display with a 120Hz refresh rate, allowing for smooth and responsive gameplay. With 16GB of RAM and a substantial 1TB NVMe M.2 SSD, this laptop ensures speedy performance and plenty of storage for games and applications. Additionally, it includes the Nvidia GeForce RTX 3050 GPU for enhanced graphics and gaming experiences.",
+                    "price": 650,
+                    "url": "https://www.dealnews.com/products/Dell/Dell-G15-Ryzen-5-15-6-Gaming-Laptop-w-Nvidia-RTX-3050/485067.html?iref=rss-c39",
+                },
+            ]
+        }
+        return DealSelection(**results)

_hf_capstone_repo/agents/specialist_agent.py

@@ -0,0 +1,90 @@
+import os
+import re
+
+from agents.agent import Agent
+from free_config import GROQ_MODEL, USE_MODAL_SPECIALIST
+
+QUESTION = "What does this cost to the nearest dollar?"
+PREFIX = "Price is $"
+
+
+class SpecialistAgent(Agent):
+    """
+    Prices products using either:
+    1. Fine-tuned Llama on Modal (best quality, uses GPU credits), or
+    2. Groq fallback (free — same prompt format as the fine-tuned model)
+
+    Set USE_MODAL_SPECIALIST=true only if you have Modal credits to spare.
+    """
+
+    name = "Specialist Agent"
+    color = Agent.RED
+
+    def __init__(self):
+        self.pricer = None
+        self.groq_client = None
+        self.mode = "off"
+        self.model = GROQ_MODEL
+
+        if USE_MODAL_SPECIALIST:
+            self._try_modal()
+
+        if self.mode == "off" and os.getenv("GROQ_API_KEY"):
+            from groq import Groq
+
+            self.groq_client = Groq(api_key=os.environ["GROQ_API_KEY"])
+            self.mode = "groq"
+            self.log(f"Specialist Agent using Groq fallback ({self.model}) — no Modal GPU needed")
+
+        if self.mode == "off":
+            self.log("Specialist Agent disabled — ensemble will use Frontier + Neural Network only")
+
+    def _try_modal(self):
+        try:
+            import modal
+
+            self.log("Specialist Agent is initializing - connecting to Modal")
+            Pricer = modal.Cls.from_name("pricer-service", "Pricer")
+            self.pricer = Pricer()
+            self.mode = "modal"
+            self.log("Specialist Agent connected to Modal pricer-service")
+        except Exception as exc:
+            self.log(f"Modal unavailable ({exc}) — will try Groq fallback if configured")
+
+    @property
+    def available(self) -> bool:
+        return self.mode != "off"
+
+    @staticmethod
+    def _parse_price(text: str) -> float:
+        if PREFIX in text:
+            text = text.split(PREFIX, 1)[1]
+        text = text.replace("$", "").replace(",", "")
+        match = re.search(r"[-+]?\d*\.\d+|\d+", text)
+        return float(match.group()) if match else 0.0
+
+    def _price_with_groq(self, description: str) -> float:
+        prompt = f"{QUESTION}\n\n{description}\n\n{PREFIX}"
+        response = self.groq_client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0,
+            max_tokens=8,
+        )
+        reply = response.choices[0].message.content or ""
+        return self._parse_price(reply)
+
+    def price(self, description: str) -> float:
+        if self.mode == "modal":
+            self.log("Specialist Agent is calling remote fine-tuned model on Modal")
+            result = self.pricer.price.remote(description)
+            self.log(f"Specialist Agent completed - predicting ${result:.2f}")
+            return result
+
+        if self.mode == "groq":
+            self.log(f"Specialist Agent is calling Groq ({self.model})")
+            result = self._price_with_groq(description)
+            self.log(f"Specialist Agent completed - predicting ${result:.2f}")
+            return result
+
+        return 0.0

_hf_capstone_repo/app.py

@@ -0,0 +1,25 @@
+"""
+Hugging Face Spaces entry point.
+
+Upload the entire week8/ folder into the Space repo root (this file becomes app.py),
+or copy week8/* into the Space and rename/move as needed.
+
+Required Space secrets: GROQ_API_KEY, HF_TOKEN, USE_MODAL_SPECIALIST=false
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# When week8 is the Space root, agents/ and deal_agent_framework.py are siblings.
+ROOT = Path(__file__).resolve().parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+os.environ.setdefault("GRADIO_SERVER_NAME", "0.0.0.0")
+os.environ.setdefault("PRICER_PREPROCESSOR_MODEL", "groq/llama-3.1-8b-instant")
+
+from price_is_right import App
+
+if __name__ == "__main__":
+    App().run()

_hf_capstone_repo/deal_agent_framework.py

@@ -0,0 +1,119 @@
+import os
+import sys
+import logging
+import json
+from typing import List
+from dotenv import load_dotenv
+import chromadb
+from agents.planning_agent import PlanningAgent
+from agents.deals import Opportunity
+from sklearn.manifold import TSNE
+import numpy as np
+
+load_dotenv(override=True)
+
+# Colors for logging
+BG_BLUE = "\033[44m"
+WHITE = "\033[37m"
+RESET = "\033[0m"
+
+# Colors for plot
+CATEGORIES = [
+    "Appliances",
+    "Automotive",
+    "Cell_Phones_and_Accessories",
+    "Electronics",
+    "Musical_Instruments",
+    "Office_Products",
+    "Tools_and_Home_Improvement",
+    "Toys_and_Games",
+]
+COLORS = ["red", "blue", "brown", "orange", "yellow", "green", "purple", "cyan"]
+
+
+def init_logging():
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(logging.INFO)
+    formatter = logging.Formatter(
+        "[%(asctime)s] [Agents] [%(levelname)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S %z",
+    )
+    handler.setFormatter(formatter)
+    root.addHandler(handler)
+
+
+class DealAgentFramework:
+    DB = "products_vectorstore"
+    MEMORY_FILENAME = "memory.json"
+
+    def __init__(self):
+        init_logging()
+        client = chromadb.PersistentClient(path=self.DB)
+        self.memory = self.read_memory()
+        self.collection = client.get_or_create_collection("products")
+        self.planner = None
+
+    def init_agents_as_needed(self):
+        if not self.planner:
+            self.log("Initializing Agent Framework")
+            self.planner = PlanningAgent(self.collection)
+            self.log("Agent Framework is ready")
+
+    def read_memory(self) -> List[Opportunity]:
+        if os.path.exists(self.MEMORY_FILENAME):
+            with open(self.MEMORY_FILENAME, "r") as file:
+                data = json.load(file)
+            opportunities = [Opportunity(**item) for item in data]
+            return opportunities
+        return []
+
+    def write_memory(self) -> None:
+        data = [opportunity.model_dump() for opportunity in self.memory]
+        with open(self.MEMORY_FILENAME, "w") as file:
+            json.dump(data, file, indent=2)
+
+    @classmethod
+    def reset_memory(cls) -> None:
+        data = []
+        if os.path.exists(cls.MEMORY_FILENAME):
+            with open(cls.MEMORY_FILENAME, "r") as file:
+                data = json.load(file)
+        truncated = data[:2]
+        with open(cls.MEMORY_FILENAME, "w") as file:
+            json.dump(truncated, file, indent=2)
+
+    def log(self, message: str):
+        text = BG_BLUE + WHITE + "[Agent Framework] " + message + RESET
+        logging.info(text)
+
+    def run(self) -> List[Opportunity]:
+        self.init_agents_as_needed()
+        logging.info("Kicking off Planning Agent")
+        result = self.planner.plan(memory=self.memory)
+        logging.info(f"Planning Agent has completed and returned: {result}")
+        if result:
+            self.memory.append(result)
+            self.write_memory()
+        return self.memory
+
+    @classmethod
+    def get_plot_data(cls, max_datapoints=2000):
+        client = chromadb.PersistentClient(path=cls.DB)
+        collection = client.get_or_create_collection("products")
+        result = collection.get(
+            include=["embeddings", "documents", "metadatas"], limit=max_datapoints
+        )
+        vectors = np.array(result["embeddings"])
+        documents = result["documents"]
+        categories = [metadata["category"] for metadata in result["metadatas"]]
+        colors = [COLORS[CATEGORIES.index(c)] for c in categories]
+        tsne = TSNE(n_components=3, random_state=42, n_jobs=-1)
+        reduced_vectors = tsne.fit_transform(vectors)
+        return documents, reduced_vectors, colors
+
+
+if __name__ == "__main__":
+    DealAgentFramework().run()

_hf_capstone_repo/env_utils.py

@@ -0,0 +1,14 @@
+"""Load .env from repo root or week8 folder."""
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+WEEK8_DIR = Path(__file__).resolve().parent
+REPO_ROOT = WEEK8_DIR.parent
+
+
+def load_project_env() -> None:
+    for path in (REPO_ROOT / ".env", WEEK8_DIR / ".env"):
+        if path.exists():
+            load_dotenv(path, override=True)

_hf_capstone_repo/free_config.py

@@ -0,0 +1,37 @@
+"""
+Free-tier configuration for Week 8 — The Price is Right.
+
+Set GROQ_API_KEY in .env for cloud LLM calls (local run + Hugging Face Spaces).
+Set USE_MODAL_SPECIALIST=true only if you want the GPU fine-tuned model on Modal.
+By default Modal is OFF — Specialist uses Groq instead (free).
+"""
+
+import os
+
+from env_utils import load_project_env
+
+load_project_env()
+
+GROQ_MODEL = os.getenv("GROQ_MODEL", "llama-3.1-8b-instant")
+LITELLM_GROQ_MODEL = f"groq/{GROQ_MODEL}"
+
+# Default false: Modal free credits are often only ~$1/month — not enough for regular GPU use.
+USE_MODAL_SPECIALIST = os.getenv("USE_MODAL_SPECIALIST", "false").lower() in ("true", "1", "yes")
+
+# Groq when an API key is present; otherwise local Ollama (local dev only).
+PREPROCESSOR_MODEL = os.getenv(
+    "PRICER_PREPROCESSOR_MODEL",
+    LITELLM_GROQ_MODEL if os.getenv("GROQ_API_KEY") else "ollama/llama3.2",
+)
+
+MESSAGING_MODEL = os.getenv("MESSAGING_MODEL", LITELLM_GROQ_MODEL)
+
+# Ensemble weights when Modal specialist is unavailable.
+WEIGHTS_WITH_SPECIALIST = (0.8, 0.1, 0.1)  # frontier, specialist, neural_network
+WEIGHTS_WITHOUT_SPECIALIST = (0.85, 0.15)  # frontier, neural_network
+
+PUSHOVER_CONFIGURED = bool(
+    os.getenv("PUSHOVER_USER")
+    and os.getenv("PUSHOVER_TOKEN")
+    and not os.getenv("PUSHOVER_USER", "").startswith("your-")
+)

_hf_capstone_repo/log_utils.py

@@ -0,0 +1,35 @@
+# Foreground colors
+RED = '\033[31m'
+GREEN = '\033[32m'
+YELLOW = '\033[33m'
+BLUE = '\033[34m'
+MAGENTA = '\033[35m'
+CYAN = '\033[36m'
+WHITE = '\033[37m'
+
+# Background color
+BG_BLACK = '\033[40m'
+BG_BLUE = '\033[44m'
+
+# Reset code to return to default color
+RESET = '\033[0m'
+
+mapper = {
+    BG_BLACK+RED: "#dd0000",
+    BG_BLACK+GREEN: "#00dd00",
+    BG_BLACK+YELLOW: "#dddd00",
+    BG_BLACK+BLUE: "#0000ee",
+    BG_BLACK+MAGENTA: "#aa00dd",
+    BG_BLACK+CYAN: "#00dddd",
+    BG_BLACK+WHITE: "#87CEEB",
+    BG_BLUE+WHITE: "#ff7800"
+}
+
+
+def reformat(message):
+    for key, value in mapper.items():
+        message = message.replace(key, f'<span style="color: {value}">')
+    message = message.replace(RESET, '</span>')
+    return message
+    
+    

_hf_capstone_repo/memory.json

@@ -0,0 +1,29 @@
+[
+  {
+    "deal": {
+      "product_description": "The Samsung Galaxy Watch Ultra is a premium 47mm LTE Titanium smartwatch designed for both style and functionality. It features a circular display made with durable materials suitable for outdoor activities, providing GPS tracking, health monitoring, and custom apps for various needs. The robust design integrates a range of smart features including notifications, music control, and heart rate tracking, making it an ideal companion for fitness enthusiasts and tech-savvy users alike.",
+      "price": 350.0,
+      "url": "https://www.dealnews.com/Samsung-Galaxy-Watch-Ultra-47-mm-LTE-Titanium-Smartwatch-up-to-350-off-w-Trade-in-free-shipping/21663266.html?iref=rss-c142"
+    },
+    "estimate": 773.8138460593241,
+    "discount": 423.8138460593241
+  },
+  {
+    "deal": {
+      "product_description": "The Refurbished Unlocked Apple iPhone 14 Pro Max offers an impressive 256GB storage and a huge display, perfect for both media consumption and productivity. Enjoy advanced camera technology for stunning photos. This model is designed to provide a seamless user experience with 5G capabilities for faster downloads and streaming. Refurbished to high standards, it comes in various colors and can support all the latest apps from the App Store, accommodating any Apple enthusiast's needs.",
+      "price": 705.0,
+      "url": "https://www.dealnews.com/products/Apple/Unlocked-Apple-iPhone-14-Pro-Max-256-GB-Smartphone/462808.html?iref=rss-c142"
+    },
+    "estimate": 930.8824204895075,
+    "discount": 225.88242048950747
+  },
+  {
+    "deal": {
+      "product_description": "This Vizio VQM55C-10 55 inch 4K QLED UHD Smart TV features 4K resolution with HDR support, Apple AirPlay 2, Google Cast, and a voice remote.",
+      "price": 248.0,
+      "url": "https://www.dealnews.com/Vizio-VQM55-C-10-55-4-K-QLED-UHD-Smart-TV-for-248-free-shipping/21998056.html?iref=rss-c142"
+    },
+    "estimate": 592.7400194091798,
+    "discount": 344.7400194091798
+  }
+]

_hf_capstone_repo/price_is_right.py

@@ -0,0 +1,208 @@
+import logging
+import os
+import queue
+import threading
+import time
+
+import gradio as gr
+import plotly.graph_objects as go
+from dotenv import load_dotenv
+
+from deal_agent_framework import DealAgentFramework
+from log_utils import reformat
+
+load_dotenv(override=True)
+
+
+class QueueHandler(logging.Handler):
+    def __init__(self, log_queue):
+        super().__init__()
+        self.log_queue = log_queue
+
+    def emit(self, record):
+        self.log_queue.put(self.format(record))
+
+
+def html_for(log_data):
+    output = "<br>".join(log_data[-18:])
+    return f"""
+    <div id="scrollContent" style="height: 400px; overflow-y: auto; border: 1px solid #ccc; background-color: #222229; padding: 10px;">
+    {output}
+    </div>
+    """
+
+
+def setup_logging(log_queue):
+    handler = QueueHandler(log_queue)
+    formatter = logging.Formatter(
+        "[%(asctime)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S %z",
+    )
+    handler.setFormatter(formatter)
+    logger = logging.getLogger()
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+
+class App:
+    def __init__(self):
+        self.agent_framework = None
+
+    def get_agent_framework(self):
+        if not self.agent_framework:
+            self.agent_framework = DealAgentFramework()
+        return self.agent_framework
+
+    def run(self):
+        with gr.Blocks(title="The Price is Right", fill_width=True) as ui:
+            log_data = gr.State([])
+
+            def table_for(opps):
+                return [
+                    [
+                        opp.deal.product_description,
+                        f"${opp.deal.price:.2f}",
+                        f"${opp.estimate:.2f}",
+                        f"${opp.discount:.2f}",
+                        opp.deal.url,
+                    ]
+                    for opp in opps
+                ]
+
+            def update_output(log_data, log_queue, result_queue):
+                initial_result = table_for(self.get_agent_framework().memory)
+                final_result = None
+                while True:
+                    try:
+                        message = log_queue.get_nowait()
+                        log_data.append(reformat(message))
+                        yield log_data, html_for(log_data), final_result or initial_result
+                    except queue.Empty:
+                        try:
+                            final_result = result_queue.get_nowait()
+                            yield log_data, html_for(log_data), final_result or initial_result
+                        except queue.Empty:
+                            if final_result is not None:
+                                break
+                            time.sleep(0.1)
+
+            def get_initial_plot():
+                fig = go.Figure()
+                fig.update_layout(
+                    title="Loading vector DB...",
+                    height=400,
+                )
+                return fig
+
+            def get_plot():
+                documents, vectors, colors = DealAgentFramework.get_plot_data(max_datapoints=800)
+                # Create the 3D scatter plot
+                fig = go.Figure(
+                    data=[
+                        go.Scatter3d(
+                            x=vectors[:, 0],
+                            y=vectors[:, 1],
+                            z=vectors[:, 2],
+                            mode="markers",
+                            marker=dict(size=2, color=colors, opacity=0.7),
+                        )
+                    ]
+                )
+
+                fig.update_layout(
+                    scene=dict(
+                        xaxis_title="x",
+                        yaxis_title="y",
+                        zaxis_title="z",
+                        aspectmode="manual",
+                        aspectratio=dict(x=2.2, y=2.2, z=1),  # Make x-axis twice as long
+                        camera=dict(
+                            eye=dict(x=1.6, y=1.6, z=0.8)  # Adjust camera position
+                        ),
+                    ),
+                    height=400,
+                    margin=dict(r=5, b=1, l=5, t=2),
+                )
+
+                return fig
+
+            def do_run():
+                new_opportunities = self.get_agent_framework().run()
+                table = table_for(new_opportunities)
+                return table
+
+            def run_with_logging(initial_log_data):
+                log_queue = queue.Queue()
+                result_queue = queue.Queue()
+                setup_logging(log_queue)
+
+                def worker():
+                    result = do_run()
+                    result_queue.put(result)
+
+                thread = threading.Thread(target=worker)
+                thread.start()
+
+                for log_data, output, final_result in update_output(
+                    initial_log_data, log_queue, result_queue
+                ):
+                    yield log_data, output, final_result
+
+            def do_select(selected_index: gr.SelectData):
+                opportunities = self.get_agent_framework().memory
+                row = selected_index.index[0]
+                opportunity = opportunities[row]
+                self.get_agent_framework().planner.messenger.alert(opportunity)
+
+            with gr.Row():
+                gr.Markdown(
+                    '<div style="text-align: center;font-size:24px"><strong>The Price is Right</strong> - Autonomous Agent Framework that hunts for deals</div>'
+                )
+            with gr.Row():
+                gr.Markdown(
+                    '<div style="text-align: center;font-size:14px">Multi-agent deal hunter: Groq LLM + RAG + optional Modal fine-tuned pricer. Finds online deals and estimates true product value.</div>'
+                )
+            with gr.Row():
+                opportunities_dataframe = gr.Dataframe(
+                    headers=["Deals found so far", "Price", "Estimate", "Discount", "URL"],
+                    wrap=True,
+                    column_widths=[6, 1, 1, 1, 3],
+                    row_count=10,
+                    col_count=5,
+                    max_height=400,
+                )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    logs = gr.HTML()
+                with gr.Column(scale=1):
+                    plot = gr.Plot(value=get_plot(), show_label=False)
+
+            ui.load(
+                run_with_logging,
+                inputs=[log_data],
+                outputs=[log_data, logs, opportunities_dataframe],
+            )
+
+            timer = gr.Timer(value=300, active=True)
+            timer.tick(
+                run_with_logging,
+                inputs=[log_data],
+                outputs=[log_data, logs, opportunities_dataframe],
+            )
+
+            opportunities_dataframe.select(do_select)
+
+        share = os.getenv("GRADIO_SHARE", "false").lower() in ("true", "1", "yes")
+        server_name = os.getenv("GRADIO_SERVER_NAME", "127.0.0.1")
+        server_port = int(os.getenv("GRADIO_SERVER_PORT", "7860"))
+        inbrowser = server_name in ("127.0.0.1", "localhost") and not share
+        ui.launch(
+            share=share,
+            server_name=server_name,
+            server_port=server_port,
+            inbrowser=inbrowser,
+        )
+
+
+if __name__ == "__main__":
+    App().run()

_hf_capstone_repo/products_vectorstore/c8498423-ab24-462f-a1fc-d9ef5751968d/data_level0.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c03e1e12c5de42db678c5308d0f09ad904f04c7dd8ee5be04be405dfc8d46c42
+size 33520000

_hf_capstone_repo/products_vectorstore/c8498423-ab24-462f-a1fc-d9ef5751968d/header.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4a8615225934162b4e8f0cae7ce25caa91aa27f6f3c15d95e448ce5434c8c406
+size 100

_hf_capstone_repo/products_vectorstore/c8498423-ab24-462f-a1fc-d9ef5751968d/index_metadata.pickle

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a4cac2085f7a9d810683f02dc31dc76daaf7b5b6658e6e322863829d174c7f84
+size 737988

_hf_capstone_repo/products_vectorstore/c8498423-ab24-462f-a1fc-d9ef5751968d/length.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:881cb357be5036b37fd074699068c05e500cf3f2e934057c3214059a8655f886
+size 80000

_hf_capstone_repo/products_vectorstore/c8498423-ab24-462f-a1fc-d9ef5751968d/link_lists.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a5736f0e6ca098dc3cf00ae4ec55862a15c1a8dd03a4fb751506dc5b6419cbee
+size 171800

_hf_capstone_repo/products_vectorstore/chroma.sqlite3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1b3cedf0c5c60f537a29524c6d05669bd74d343dd18bb95f5e247567d94b2f2a
+size 59838464

_hf_capstone_repo/requirements.txt

@@ -0,0 +1,17 @@
+gradio>=5.47.2,<6.0
+chromadb>=1.1.0
+sentence-transformers>=5.1.1
+groq>=0.33.0
+litellm>=1.77.5
+python-dotenv>=1.1.1
+pydantic>=2.0
+beautifulsoup4>=4.14.2
+feedparser>=6.0.12
+requests>=2.32.5
+numpy>=2.3.3
+scikit-learn>=1.7.2
+plotly>=6.3.0
+pandas>=2.3.3
+torch>=2.8.0
+modal>=1.1.4
+tqdm>=4.67.1

_hf_deploy/.gitattributes

@@ -0,0 +1,2 @@
+*.pth filter=lfs diff=lfs merge=lfs -text
+products_vectorstore/** filter=lfs diff=lfs merge=lfs -text

_hf_deploy/README.md

@@ -0,0 +1,21 @@
+---
+title: Capstone - The Price Is Right
+emoji: 💰
+colorFrom: blue
+colorTo: green
+sdk: gradio
+sdk_version: "5.47.2"
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Capstone — The Price Is Right
+
+Multi-agent deal hunting AI for the LLM Engineering capstone project.
+
+- Scans DealNews RSS feeds for deals
+- Estimates true product prices with RAG + Groq + neural network
+- Surfaces bargains in a live Gradio dashboard
+
+**Secrets required:** `GROQ_API_KEY`, `HF_TOKEN`, `USE_MODAL_SPECIALIST=false`, `GRADIO_SERVER_NAME=0.0.0.0`

_hf_deploy/agents/agent.py

@@ -0,0 +1,33 @@
+import logging
+
+class Agent:
+    """
+    An abstract superclass for Agents
+    Used to log messages in a way that can identify each Agent
+    """
+
+    # Foreground colors
+    RED = '\033[31m'
+    GREEN = '\033[32m'
+    YELLOW = '\033[33m'
+    BLUE = '\033[34m'
+    MAGENTA = '\033[35m'
+    CYAN = '\033[36m'
+    WHITE = '\033[37m'
+    
+    # Background color
+    BG_BLACK = '\033[40m'
+    
+    # Reset code to return to default color
+    RESET = '\033[0m'
+
+    name: str = ""
+    color: str = '\033[37m'
+
+    def log(self, message):
+        """
+        Log this as an info message, identifying the agent
+        """
+        color_code = self.BG_BLACK + self.color
+        message = f"[{self.name}] {message}"
+        logging.info(color_code + message + self.RESET)

_hf_deploy/agents/autonomous_planning_agent.py

@@ -0,0 +1,181 @@
+from typing import Optional, List, Dict
+from agents.agent import Agent
+from agents.deals import Deal, Opportunity
+from agents.scanner_agent import ScannerAgent
+from agents.ensemble_agent import EnsembleAgent
+from agents.messaging_agent import MessagingAgent
+from openai import OpenAI
+import json
+
+
+class AutonomousPlanningAgent(Agent):
+    name = "Autonomous Planning Agent"
+    color = Agent.GREEN
+    MODEL = "gpt-5.1"
+
+    def __init__(self, collection):
+        """
+        Create instances of the 3 Agents that this planner coordinates across
+        """
+        self.log("Autonomous Planning Agent is initializing")
+        self.scanner = ScannerAgent()
+        self.ensemble = EnsembleAgent(collection)
+        self.messenger = MessagingAgent()
+        self.openai = OpenAI()
+        self.memory = None
+        self.opportunity = None
+        self.log("Autonomous Planning Agent is ready")
+
+    def scan_the_internet_for_bargains(self) -> str:
+        """
+        Run the tool to scan
+        """
+        self.log("Autonomous Planning agent is calling scanner")
+        results = self.scanner.scan(memory=self.memory)
+        return results.model_dump_json() if results else "No deals found"
+
+    def estimate_true_value(self, description: str) -> str:
+        """
+        Run the tool to estimate true value
+        """
+        self.log("Autonomous Planning agent is estimating value via Ensemble Agent")
+        estimate = self.ensemble.price(description)
+        return f"The estimated true value of {description} is {estimate}"
+
+    def notify_user_of_deal(
+        self, description: str, deal_price: float, estimated_true_value: float, url: str
+    ) -> Dict:
+        """
+        Run the tool to notify the user
+        """
+        if self.opportunity:
+            self.log("Autonomous Planning agent is trying to notify the user a 2nd time; ignoring")
+        else:
+            self.log("Autonomous Planning agent is notifying user")
+            self.messenger.notify(description, deal_price, estimated_true_value, url)
+            deal = Deal(product_description=description, price=deal_price, url=url)
+            discount = estimated_true_value - deal_price
+            self.opportunity = Opportunity(
+                deal=deal, estimate=estimated_true_value, discount=discount
+            )
+        return "Notification sent ok"
+
+    scan_function = {
+        "name": "scan_the_internet_for_bargains",
+        "description": "Returns top bargains scraped from the internet along with the price each item is being offered for",
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+            "additionalProperties": False,
+        },
+    }
+
+    estimate_function = {
+        "name": "estimate_true_value",
+        "description": "Given the description of an item, estimate how much it is actually worth",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "The description of the item to be estimated",
+                },
+            },
+            "required": ["description"],
+            "additionalProperties": False,
+        },
+    }
+
+    notify_function = {
+        "name": "notify_user_of_deal",
+        "description": "Send the user a push notification about the single most compelling deal; only call this one time",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "The description of the item itself scraped from the internet",
+                },
+                "deal_price": {
+                    "type": "number",
+                    "description": "The price offered by this deal scraped from the internet",
+                },
+                "estimated_true_value": {
+                    "type": "number",
+                    "description": "The estimated actual value that this is worth",
+                },
+                "url": {
+                    "type": "string",
+                    "description": "The URL of this deal as scraped from the internet",
+                },
+            },
+            "required": ["description", "deal_price", "estimated_true_value", "url"],
+            "additionalProperties": False,
+        },
+    }
+
+    def get_tools(self):
+        """
+        Return the json for the tools to be used
+        """
+        return [
+            {"type": "function", "function": self.scan_function},
+            {"type": "function", "function": self.estimate_function},
+            {"type": "function", "function": self.notify_function},
+        ]
+
+    def handle_tool_call(self, message):
+        """
+        Actually call the tools associated with this message
+        """
+        mapping = {
+            "scan_the_internet_for_bargains": self.scan_the_internet_for_bargains,
+            "estimate_true_value": self.estimate_true_value,
+            "notify_user_of_deal": self.notify_user_of_deal,
+        }
+        results = []
+        for tool_call in message.tool_calls:
+            tool_name = tool_call.function.name
+            arguments = json.loads(tool_call.function.arguments)
+            tool = mapping.get(tool_name)
+            result = tool(**arguments) if tool else ""
+            results.append({"role": "tool", "content": result, "tool_call_id": tool_call.id})
+        return results
+
+    system_message = "You find great deals on bargain products using your tools, and notify the user of the best bargain."
+    user_message = """
+    First, use your tool to scan the internet for bargain deals. Then for each deal, use your tool to estimate its true value.
+    Then pick the single most compelling deal where the price is much lower than the estimated true value, and use your tool to notify the user.
+    Then just reply OK to indicate success.
+    """
+    messages = [
+        {"role": "system", "content": system_message},
+        {"role": "user", "content": user_message},
+    ]
+
+    def plan(self, memory: List[str] = []) -> Optional[Opportunity]:
+        """
+        Run the full workflow, providing the LLM with tools to surface scraped deals to the user
+        :param memory: a list of URLs that have been surfaced in the past
+        :return: an Opportunity if one was surfaced, otherwise None
+        """
+        self.log("Autonomous Planning Agent is kicking off a run")
+        self.memory = memory
+        self.opportunity = None
+        messages = self.messages[:]
+        done = False
+        while not done:
+            response = self.openai.chat.completions.create(
+                model=self.MODEL, messages=messages, tools=self.get_tools()
+            )
+            if response.choices[0].finish_reason == "tool_calls":
+                message = response.choices[0].message
+                results = self.handle_tool_call(message)
+                messages.append(message)
+                messages.extend(results)
+            else:
+                done = True
+        reply = response.choices[0].message.content
+        self.log(f"Autonomous Planning Agent completed with: {reply}")
+        return self.opportunity

_hf_deploy/agents/deals.py

@@ -0,0 +1,134 @@
+from pydantic import BaseModel, Field
+from typing import List, Dict, Self
+from bs4 import BeautifulSoup
+import re
+import feedparser
+from tqdm import tqdm
+import requests
+import time
+
+feeds = [
+    "https://www.dealnews.com/c142/Electronics/?rss=1",
+    "https://www.dealnews.com/c39/Computers/?rss=1",
+    "https://www.dealnews.com/f1912/Smart-Home/?rss=1",
+]
+
+# You could also add: "https://www.dealnews.com/c238/Automotive/?rss=1"
+# "https://www.dealnews.com/c196/Home-Garden/?rss=1"
+
+
+def extract(html_snippet: str) -> str:
+    """
+    Use Beautiful Soup to clean up this HTML snippet and extract useful text
+    """
+    soup = BeautifulSoup(html_snippet, "html.parser")
+    snippet_div = soup.find("div", class_="snippet summary")
+
+    if snippet_div:
+        description = snippet_div.get_text(strip=True)
+        description = BeautifulSoup(description, "html.parser").get_text()
+        description = re.sub("<[^<]+?>", "", description)
+        result = description.strip()
+    else:
+        result = html_snippet
+    return result.replace("\n", " ")
+
+
+class ScrapedDeal:
+    """
+    A class to represent a Deal retrieved from an RSS feed
+    """
+
+    category: str
+    title: str
+    summary: str
+    url: str
+    details: str
+    features: str
+
+    def __init__(self, entry: Dict[str, str]):
+        """
+        Populate this instance based on the provided dict
+        """
+        self.title = entry["title"]
+        self.summary = extract(entry["summary"])
+        self.url = entry["links"][0]["href"]
+        stuff = requests.get(self.url).content
+        soup = BeautifulSoup(stuff, "html.parser")
+        content = soup.find("div", class_="content-section").get_text()
+        content = content.replace("\nmore", "").replace("\n", " ")
+        if "Features" in content:
+            self.details, self.features = content.split("Features", 1)
+        else:
+            self.details = content
+            self.features = ""
+        self.truncate()
+
+    def truncate(self):
+        """
+        Limit the fields to a sensible length to avoid sending too much info to the model
+        """
+        self.title = self.title[:100]
+        self.details = self.details[:500]
+        self.features = self.features[:500]
+
+    def __repr__(self):
+        """
+        Return a string to describe this deal
+        """
+        return f"<{self.title}>"
+
+    def describe(self):
+        """
+        Return a longer string to describe this deal for use in calling a model
+        """
+        return f"Title: {self.title}\nDetails: {self.details.strip()}\nFeatures: {self.features.strip()}\nURL: {self.url}"
+
+    @classmethod
+    def fetch(cls, show_progress: bool = False) -> List[Self]:
+        """
+        Retrieve all deals from the selected RSS feeds
+        """
+        deals = []
+        feed_iter = tqdm(feeds) if show_progress else feeds
+        for feed_url in feed_iter:
+            feed = feedparser.parse(feed_url)
+            for entry in feed.entries[:10]:
+                deals.append(cls(entry))
+                time.sleep(0.05)
+        return deals
+
+
+class Deal(BaseModel):
+    """
+    A class to Represent a Deal with a summary description
+    """
+
+    product_description: str = Field(
+        description="Your clearly expressed summary of the product in 3-4 sentences. Details of the item are much more important than why it's a good deal. Avoid mentioning discounts and coupons; focus on the item itself. There should be a short paragraph of text for each item you choose."
+    )
+    price: float = Field(
+        description="The actual price of this product, as advertised in the deal. Be sure to give the actual price; for example, if a deal is described as $100 off the usual $300 price, you should respond with $200"
+    )
+    url: str = Field(description="The URL of the deal, as provided in the input")
+
+
+class DealSelection(BaseModel):
+    """
+    A class to Represent a list of Deals
+    """
+
+    deals: List[Deal] = Field(
+        description="Your selection of the 5 deals that have the most detailed, high quality description and the most clear price. You should be confident that the price reflects the deal, that it is a good deal, with a clear description"
+    )
+
+
+class Opportunity(BaseModel):
+    """
+    A class to represent a possible opportunity: a Deal where we estimate
+    it should cost more than it's being offered
+    """
+
+    deal: Deal
+    estimate: float
+    discount: float

_hf_deploy/agents/deep_neural_network.py

@@ -0,0 +1,101 @@
+import numpy as np
+from tqdm.notebook import tqdm
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, TensorDataset
+from torch.optim.lr_scheduler import CosineAnnealingLR
+from sklearn.feature_extraction.text import HashingVectorizer
+import logging
+
+
+class ResidualBlock(nn.Module):
+    def __init__(self, hidden_size, dropout_prob):
+        super(ResidualBlock, self).__init__()
+        self.block = nn.Sequential(
+            nn.Linear(hidden_size, hidden_size),
+            nn.LayerNorm(hidden_size),
+            nn.ReLU(),
+            nn.Dropout(dropout_prob),
+            nn.Linear(hidden_size, hidden_size),
+            nn.LayerNorm(hidden_size),
+        )
+        self.relu = nn.ReLU()
+
+    def forward(self, x):
+        residual = x
+        out = self.block(x)
+        out += residual  # Skip connection
+        return self.relu(out)
+
+
+class DeepNeuralNetwork(nn.Module):
+    def __init__(self, input_size, num_layers=10, hidden_size=4096, dropout_prob=0.2):
+        super(DeepNeuralNetwork, self).__init__()
+
+        # First layer
+        self.input_layer = nn.Sequential(
+            nn.Linear(input_size, hidden_size),
+            nn.LayerNorm(hidden_size),
+            nn.ReLU(),
+            nn.Dropout(dropout_prob),
+        )
+
+        # Residual blocks
+        self.residual_blocks = nn.ModuleList()
+        for i in range(num_layers - 2):
+            self.residual_blocks.append(ResidualBlock(hidden_size, dropout_prob))
+
+        # Output layer
+        self.output_layer = nn.Linear(hidden_size, 1)
+
+    def forward(self, x):
+        x = self.input_layer(x)
+
+        for block in self.residual_blocks:
+            x = block(x)
+
+        return self.output_layer(x)
+
+
+Y_STD = 1.0328539609909058
+Y_MEAN = 4.434937953948975
+
+
+class DeepNeuralNetworkInference:
+    def __init__(self):
+        self.vectorizer = None
+        self.model = None
+        self.device = None
+
+        np.random.seed(42)
+        torch.manual_seed(42)
+        torch.cuda.manual_seed(42)
+
+    def setup(self):
+        self.vectorizer = HashingVectorizer(n_features=5000, stop_words="english", binary=True)
+        self.model = DeepNeuralNetwork(5000)
+        if torch.cuda.is_available():
+            self.device = torch.device("cuda")
+        elif torch.backends.mps.is_available():
+            self.device = torch.device("mps")
+        else:
+            self.device = torch.device("cpu")
+
+        logging.info(f"Neural Network is using {self.device}")
+
+        self.model.to(self.device)
+
+    def load(self, path):
+        self.model.load_state_dict(torch.load(path, map_location=self.device))
+        self.model.to(self.device)
+
+    def inference(self, text):
+        self.model.eval()
+        with torch.no_grad():
+            vector = self.vectorizer.transform([text])
+            vector = torch.FloatTensor(vector.toarray()).to(self.device)
+            pred = self.model(vector)[0]
+            result = torch.exp(pred * Y_STD + Y_MEAN) - 1
+            result = result.item()
+        return max(0, result)

_hf_deploy/agents/ensemble_agent.py

@@ -0,0 +1,51 @@
+from agents.agent import Agent
+from agents.specialist_agent import SpecialistAgent
+from agents.frontier_agent import FrontierAgent
+from agents.neural_network_agent import NeuralNetworkAgent
+from agents.preprocessor import Preprocessor
+from free_config import WEIGHTS_WITH_SPECIALIST, WEIGHTS_WITHOUT_SPECIALIST
+
+
+class EnsembleAgent(Agent):
+    name = "Ensemble Agent"
+    color = Agent.YELLOW
+
+    def __init__(self, collection):
+        """
+        Create an instance of Ensemble, by creating each of the models
+        And loading the weights of the Ensemble
+        """
+        self.log("Initializing Ensemble Agent")
+        self.specialist = SpecialistAgent()
+        self.frontier = FrontierAgent(collection)
+        self.neural_network = NeuralNetworkAgent()
+        self.preprocessor = Preprocessor()
+        self.use_specialist = self.specialist.available
+        if self.use_specialist:
+            mode = getattr(self.specialist, "mode", "on")
+            self.log(f"Ensemble Agent is ready (Frontier + Specialist [{mode}] + Neural Network)")
+        else:
+            self.log("Ensemble Agent is ready (Frontier + Neural Network only)")
+
+    def price(self, description: str) -> float:
+        """
+        Run this ensemble model
+        Ask each of the models to price the product
+        Then return the weighted average price
+        """
+        self.log("Running Ensemble Agent - preprocessing text")
+        rewrite = self.preprocessor.preprocess(description)
+        self.log(f"Pre-processed text using {self.preprocessor.model_name}")
+        frontier = self.frontier.price(rewrite)
+        neural_network = self.neural_network.price(rewrite)
+
+        if self.use_specialist:
+            specialist = self.specialist.price(rewrite)
+            wf, ws, wn = WEIGHTS_WITH_SPECIALIST
+            combined = frontier * wf + specialist * ws + neural_network * wn
+        else:
+            wf, wn = WEIGHTS_WITHOUT_SPECIALIST
+            combined = frontier * wf + neural_network * wn
+
+        self.log(f"Ensemble Agent complete - returning ${combined:.2f}")
+        return combined

_hf_deploy/agents/evaluator.py

@@ -0,0 +1,218 @@
+import re
+from sklearn.metrics import mean_squared_error, r2_score
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+from itertools import accumulate
+import math
+from tqdm.notebook import tqdm
+from concurrent.futures import ThreadPoolExecutor
+
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+RED = "\033[91m"
+RESET = "\033[0m"
+COLOR_MAP = {"red": RED, "orange": YELLOW, "green": GREEN}
+
+WORKERS = 5
+DEFAULT_SIZE = 200
+
+
+class Tester:
+    def __init__(self, predictor, data, title=None, size=DEFAULT_SIZE, workers=WORKERS):
+        self.predictor = predictor
+        self.data = data
+        self.title = title or self.make_title(predictor)
+        self.size = size
+        self.titles = []
+        self.guesses = []
+        self.truths = []
+        self.errors = []
+        self.colors = []
+        self.workers = workers
+
+    @staticmethod
+    def make_title(predictor) -> str:
+        return predictor.__name__.replace("__", ".").replace("_", " ").title().replace("Gpt", "GPT")
+
+    @staticmethod
+    def post_process(value):
+        if isinstance(value, str):
+            value = value.replace("$", "").replace(",", "")
+            match = re.search(r"[-+]?\d*\.\d+|\d+", value)
+            return float(match.group()) if match else 0
+        else:
+            return value
+
+    def color_for(self, error, truth):
+        if error < 40 or error / truth < 0.2:
+            return "green"
+        elif error < 80 or error / truth < 0.4:
+            return "orange"
+        else:
+            return "red"
+
+    def run_datapoint(self, i):
+        datapoint = self.data[i]
+        value = self.predictor(datapoint)
+        guess = self.post_process(value)
+        truth = datapoint.price
+        error = abs(guess - truth)
+        color = self.color_for(error, truth)
+        title = datapoint.title if len(datapoint.title) <= 40 else datapoint.title[:40] + "..."
+        return title, guess, truth, error, color
+
+    def chart(self, title):
+        df = pd.DataFrame(
+            {
+                "truth": self.truths,
+                "guess": self.guesses,
+                "title": self.titles,
+                "error": self.errors,
+                "color": self.colors,
+            }
+        )
+
+        # Pre-format hover text
+        df["hover"] = [
+            f"{t}\nGuess=${g:,.2f} Actual=${y:,.2f}"
+            for t, g, y in zip(df["title"], df["guess"], df["truth"])
+        ]
+
+        max_val = float(max(df["truth"].max(), df["guess"].max()))
+
+        fig = px.scatter(
+            df,
+            x="truth",
+            y="guess",
+            color="color",
+            color_discrete_map={"green": "green", "orange": "orange", "red": "red"},
+            title=title,
+            labels={"truth": "Actual Price", "guess": "Predicted Price"},
+            width=1000,
+            height=800,
+        )
+
+        # Assign customdata per trace (one color/category = one trace)
+        for tr in fig.data:
+            mask = df["color"] == tr.name
+            tr.customdata = df.loc[mask, ["hover"]].to_numpy()
+            tr.hovertemplate = "%{customdata[0]}<extra></extra>"
+            tr.marker.update(size=6)
+
+        # Reference line y=x
+        fig.add_trace(
+            go.Scatter(
+                x=[0, max_val],
+                y=[0, max_val],
+                mode="lines",
+                line=dict(width=2, dash="dash", color="deepskyblue"),
+                name="y = x",
+                hoverinfo="skip",
+                showlegend=False,
+            )
+        )
+
+        fig.update_xaxes(range=[0, max_val])
+        fig.update_yaxes(range=[0, max_val])
+        fig.update_layout(showlegend=False)
+        fig.show()
+
+    def error_trend_chart(self):
+        n = len(self.errors)
+
+        # Running mean and std (pure Python)
+        running_sums = list(accumulate(self.errors))
+        x = list(range(1, n + 1))
+        running_means = [s / i for s, i in zip(running_sums, x)]
+
+        running_squares = list(accumulate(e * e for e in self.errors))
+        running_stds = [
+            math.sqrt((sq_sum / i) - (mean**2)) if i > 1 else 0
+            for i, sq_sum, mean in zip(x, running_squares, running_means)
+        ]
+
+        # 95% confidence interval for mean
+        ci = [1.96 * (sd / math.sqrt(i)) if i > 1 else 0 for i, sd in zip(x, running_stds)]
+        upper = [m + c for m, c in zip(running_means, ci)]
+        lower = [m - c for m, c in zip(running_means, ci)]
+
+        # Plot
+        fig = go.Figure()
+
+        # Shaded confidence interval band
+        fig.add_trace(
+            go.Scatter(
+                x=x + x[::-1],
+                y=upper + lower[::-1],
+                fill="toself",
+                fillcolor="rgba(128,128,128,0.2)",
+                line=dict(color="rgba(255,255,255,0)"),
+                hoverinfo="skip",
+                showlegend=False,
+                name="95% CI",
+            )
+        )
+
+        # Main line with hover text showing CI
+        fig.add_trace(
+            go.Scatter(
+                x=x,
+                y=running_means,
+                mode="lines",
+                line=dict(width=3, color="firebrick"),
+                name="Cumulative Avg Error",
+                customdata=list(
+                    zip(
+                        ci,
+                    )
+                ),
+                hovertemplate=(
+                    "n=%{x}<br>"
+                    "Avg Error=$%{y:,.2f}<br>"
+                    "±95% CI=$%{customdata[0]:,.2f}<extra></extra>"
+                ),
+            )
+        )
+
+        # Title with final stats
+        final_mean = running_means[-1]
+        final_ci = ci[-1]
+        title = f"{self.title} Error: ${final_mean:,.2f} ± ${final_ci:,.2f}"
+
+        fig.update_layout(
+            title=title,
+            xaxis_title="Number of Datapoints",
+            yaxis_title="Average Absolute Error ($)",
+            width=1000,
+            height=360,
+            template="plotly_white",
+            showlegend=False,
+        )
+
+        fig.show()
+
+    def report(self):
+        average_error = sum(self.errors) / self.size
+        mse = mean_squared_error(self.truths, self.guesses)
+        r2 = r2_score(self.truths, self.guesses) * 100
+        title = f"{self.title} results<br><b>Error:</b> ${average_error:,.2f} <b>MSE:</b> {mse:,.0f} <b>r²:</b> {r2:.1f}%"
+        self.error_trend_chart()
+        self.chart(title)
+
+    def run(self):
+        with ThreadPoolExecutor(max_workers=self.workers) as ex:
+            for title, guess, truth, error, color in tqdm(
+                ex.map(self.run_datapoint, range(self.size)), total=self.size
+            ):
+                self.titles.append(title)
+                self.guesses.append(guess)
+                self.truths.append(truth)
+                self.errors.append(error)
+                self.colors.append(color)
+                print(f"{COLOR_MAP[color]}${error:.0f} ", end="")
+        self.report()
+
+
+def evaluate(function, data, size=DEFAULT_SIZE, workers=WORKERS):
+    Tester(function, data, size=size, workers=workers).run()

_hf_deploy/agents/frontier_agent.py

@@ -0,0 +1,86 @@
+import os
+import re
+from typing import List, Dict
+
+from groq import Groq
+from sentence_transformers import SentenceTransformer
+
+from agents.agent import Agent
+from free_config import GROQ_MODEL
+
+
+class FrontierAgent(Agent):
+    name = "Frontier Agent"
+    color = Agent.BLUE
+
+    def __init__(self, collection):
+        """
+        Set up this instance by connecting to Groq, the Chroma datastore,
+        and the local sentence-transformer embedding model.
+        """
+        self.log("Initializing Frontier Agent")
+        self.client = Groq(api_key=os.environ["GROQ_API_KEY"])
+        self.model = GROQ_MODEL
+        self.log(f"Frontier Agent is setting up with Groq ({self.model})")
+        self.collection = collection
+        self.encoder = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
+        self.log("Frontier Agent is ready")
+
+    def make_context(self, similars: List[str], prices: List[float]) -> str:
+        """
+        Create context that can be inserted into the prompt
+        """
+        message = "To provide some context, here are some other items that might be similar to the item you need to estimate.\n\n"
+        for similar, price in zip(similars, prices):
+            message += f"Potentially related product:\n{similar}\nPrice is ${price:.2f}\n\n"
+        return message
+
+    def messages_for(
+        self, description: str, similars: List[str], prices: List[float]
+    ) -> List[Dict[str, str]]:
+        """
+        Create the message list for the Groq chat completion call
+        """
+        message = f"Estimate the price of this product. Respond with the price only, no explanation.\n\n{description}\n\n"
+        message += self.make_context(similars, prices)
+        return [{"role": "user", "content": message}]
+
+    def find_similars(self, description: str):
+        """
+        Return a list of items similar to the given one by looking in the Chroma datastore
+        """
+        self.log(
+            "Frontier Agent is performing a RAG search of the Chroma datastore to find 5 similar products"
+        )
+        vector = self.encoder.encode([description])
+        results = self.collection.query(query_embeddings=vector.astype(float).tolist(), n_results=5)
+        documents = results["documents"][0][:]
+        prices = [m["price"] for m in results["metadatas"][0][:]]
+        self.log("Frontier Agent has found similar products")
+        return documents, prices
+
+    def get_price(self, s) -> float:
+        """
+        A utility that plucks a floating point number out of a string
+        """
+        s = s.replace("$", "").replace(",", "")
+        match = re.search(r"[-+]?\d*\.\d+|\d+", s)
+        return float(match.group()) if match else 0.0
+
+    def price(self, description: str) -> float:
+        """
+        Call Groq to estimate the price using RAG context from similar products.
+        """
+        documents, prices = self.find_similars(description)
+        self.log(
+            f"Frontier Agent is about to call Groq ({self.model}) with context including 5 similar products"
+        )
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=self.messages_for(description, documents, prices),
+            temperature=0,
+        )
+        reply = response.choices[0].message.content
+        result = self.get_price(reply)
+        self.log(f"Frontier Agent completed - predicting ${result:.2f}")
+        return result

_hf_deploy/agents/items.py

@@ -0,0 +1,52 @@
+from pydantic import BaseModel
+from datasets import Dataset, DatasetDict, load_dataset
+from typing import Optional, Self
+
+
+PREFIX = "Price is $"
+QUESTION = "What does this cost to the nearest dollar?"
+
+
+class Item(BaseModel):
+    """
+    An Item is a data-point of a Product with a Price
+    """
+
+    title: str
+    category: str
+    price: float
+    full: Optional[str] = None
+    weight: Optional[float] = None
+    summary: Optional[str] = None
+    prompt: Optional[str] = None
+    id: Optional[int] = None
+
+    def make_prompt(self, text: str):
+        self.prompt = f"{QUESTION}\n\n{text}\n\n{PREFIX}{round(self.price)}.00"
+
+    def test_prompt(self) -> str:
+        return self.prompt.split(PREFIX)[0] + PREFIX
+
+    def __repr__(self) -> str:
+        return f"<{self.title} = ${self.price}>"
+
+    @staticmethod
+    def push_to_hub(dataset_name: str, train: list[Self], val: list[Self], test: list[Self]):
+        """Push Item lists to HuggingFace Hub"""
+        DatasetDict(
+            {
+                "train": Dataset.from_list([item.model_dump() for item in train]),
+                "validation": Dataset.from_list([item.model_dump() for item in val]),
+                "test": Dataset.from_list([item.model_dump() for item in test]),
+            }
+        ).push_to_hub(dataset_name)
+
+    @classmethod
+    def from_hub(cls, dataset_name: str) -> tuple[list[Self], list[Self], list[Self]]:
+        """Load from HuggingFace Hub and reconstruct Items"""
+        ds = load_dataset(dataset_name)
+        return (
+            [cls.model_validate(row) for row in ds["train"]],
+            [cls.model_validate(row) for row in ds["validation"]],
+            [cls.model_validate(row) for row in ds["test"]],
+        )

_hf_deploy/agents/messaging_agent.py

@@ -0,0 +1,79 @@
+import os
+
+import requests
+from litellm import completion
+
+from agents.deals import Opportunity
+from agents.agent import Agent
+from free_config import MESSAGING_MODEL, PUSHOVER_CONFIGURED
+
+pushover_url = "https://api.pushover.net/1/messages.json"
+
+
+class MessagingAgent(Agent):
+    name = "Messaging Agent"
+    color = Agent.WHITE
+
+    def __init__(self):
+        """
+        Set up Pushover notifications (optional) and Groq for message crafting.
+        """
+        self.log("Messaging Agent is initializing")
+        self.pushover_user = os.getenv("PUSHOVER_USER", "")
+        self.pushover_token = os.getenv("PUSHOVER_TOKEN", "")
+        self.model = MESSAGING_MODEL
+        if PUSHOVER_CONFIGURED:
+            self.log("Messaging Agent has Pushover configured")
+        else:
+            self.log("Messaging Agent: Pushover not configured — alerts will be logged only")
+
+    def push(self, text):
+        """
+        Send a Push Notification using the Pushover API, or log if not configured.
+        """
+        if not PUSHOVER_CONFIGURED:
+            self.log(f"Deal alert (Pushover skipped): {text[:120]}...")
+            return
+        self.log("Messaging Agent is sending a push notification")
+        payload = {
+            "user": self.pushover_user,
+            "token": self.pushover_token,
+            "message": text,
+            "sound": "cashregister",
+        }
+        requests.post(pushover_url, data=payload)
+
+    def alert(self, opportunity: Opportunity):
+        """
+        Make an alert about the specified Opportunity
+        """
+        text = f"Deal Alert! Price=${opportunity.deal.price:.2f}, "
+        text += f"Estimate=${opportunity.estimate:.2f}, "
+        text += f"Discount=${opportunity.discount:.2f} :"
+        text += opportunity.deal.product_description[:10] + "... "
+        text += opportunity.deal.url
+        self.push(text)
+        self.log("Messaging Agent has completed")
+
+    def craft_message(
+        self, description: str, deal_price: float, estimated_true_value: float
+    ) -> str:
+        user_prompt = "Please summarize this great deal in 2-3 sentences to be sent as an exciting push notification alerting the user about this deal.\n"
+        user_prompt += f"Item Description: {description}\nOffered Price: {deal_price}\nEstimated true value: {estimated_true_value}"
+        user_prompt += "\n\nRespond only with the 2-3 sentence message which will be used to alert & excite the user about this deal"
+        response = completion(
+            model=self.model,
+            messages=[
+                {"role": "user", "content": user_prompt},
+            ],
+        )
+        return response.choices[0].message.content
+
+    def notify(self, description: str, deal_price: float, estimated_true_value: float, url: str):
+        """
+        Make an alert about the specified details
+        """
+        self.log(f"Messaging Agent is using Groq ({self.model}) to craft the message")
+        text = self.craft_message(description, deal_price, estimated_true_value)
+        self.push(text[:200] + "... " + url)
+        self.log("Messaging Agent has completed")

_hf_deploy/agents/neural_network_agent.py

@@ -0,0 +1,29 @@
+from agents.agent import Agent
+from agents.deep_neural_network import DeepNeuralNetworkInference
+
+
+class NeuralNetworkAgent(Agent):
+    name = "Neural Network Agent"
+    color = Agent.MAGENTA
+
+    def __init__(self):
+        """
+        Initialize this object by loading in the saved model weights
+        and the SentenceTransformer vector encoding model
+        """
+        self.log("Neural Network Agent is initializing")
+        self.neural_network = DeepNeuralNetworkInference()
+        self.neural_network.setup()
+        self.neural_network.load("deep_neural_network.pth")
+        self.log("Neural Network Agent is ready and weights are loaded")
+
+    def price(self, description: str) -> float:
+        """
+        Use the Deep Neural Network to estimate the price of the described item
+        :param description: the product to be estimated
+        :return: the price as a float
+        """
+        self.log("Neural Network Agent is starting a prediction")
+        result = self.neural_network.inference(description)
+        self.log(f"Neural Network Agent completed - predicting ${result:.2f}")
+        return result

_hf_deploy/agents/planning_agent.py

@@ -0,0 +1,57 @@
+from typing import Optional, List
+from agents.agent import Agent
+from agents.deals import ScrapedDeal, DealSelection, Deal, Opportunity
+from agents.scanner_agent import ScannerAgent
+from agents.ensemble_agent import EnsembleAgent
+from agents.messaging_agent import MessagingAgent
+
+
+class PlanningAgent(Agent):
+
+    name = "Planning Agent"
+    color = Agent.GREEN
+    DEAL_THRESHOLD = 50
+
+    def __init__(self, collection):
+        """
+        Create instances of the 3 Agents that this planner coordinates across
+        """
+        self.log("Planning Agent is initializing")
+        self.scanner = ScannerAgent()
+        self.ensemble = EnsembleAgent(collection)
+        self.messenger = MessagingAgent()
+        self.log("Planning Agent is ready")
+
+    def run(self, deal: Deal) -> Opportunity:
+        """
+        Run the workflow for a particular deal
+        :param deal: the deal, summarized from an RSS scrape
+        :returns: an opportunity including the discount
+        """
+        self.log("Planning Agent is pricing up a potential deal")
+        estimate = self.ensemble.price(deal.product_description)
+        discount = estimate - deal.price
+        self.log(f"Planning Agent has processed a deal with discount ${discount:.2f}")
+        return Opportunity(deal=deal, estimate=estimate, discount=discount)
+
+    def plan(self, memory: List[str] = []) -> Optional[Opportunity]:
+        """
+        Run the full workflow:
+        1. Use the ScannerAgent to find deals from RSS feeds
+        2. Use the EnsembleAgent to estimate them
+        3. Use the MessagingAgent to send a notification of deals
+        :param memory: a list of URLs that have been surfaced in the past
+        :return: an Opportunity if one was surfaced, otherwise None
+        """
+        self.log("Planning Agent is kicking off a run")
+        selection = self.scanner.scan(memory=memory)
+        if selection:
+            opportunities = [self.run(deal) for deal in selection.deals[:5]]
+            opportunities.sort(key=lambda opp: opp.discount, reverse=True)
+            best = opportunities[0]
+            self.log(f"Planning Agent has identified the best deal has discount ${best.discount:.2f}")
+            if best.discount > self.DEAL_THRESHOLD:
+                self.messenger.alert(best)
+            self.log("Planning Agent has completed a run")
+            return best if best.discount > self.DEAL_THRESHOLD else None
+        return None

_hf_deploy/agents/preprocessor.py

@@ -0,0 +1,50 @@
+import os
+
+from dotenv import load_dotenv
+from litellm import completion
+
+from free_config import PREPROCESSOR_MODEL
+
+load_dotenv(override=True)
+
+DEFAULT_REASONING_EFFORT = "low" if "gpt-oss" in PREPROCESSOR_MODEL else None
+
+SYSTEM_PROMPT = """Create a concise description of a product. Respond only in this format. Do not include part numbers.
+Title: Rewritten short precise title
+Category: eg Electronics
+Brand: Brand name
+Description: 1 sentence description
+Details: 1 sentence on features"""
+
+
+class Preprocessor:
+    def __init__(
+        self,
+        model_name=PREPROCESSOR_MODEL,
+        reasoning_effort=DEFAULT_REASONING_EFFORT,
+        base_url=None,
+    ):
+        self.total_input_tokens = 0
+        self.total_output_tokens = 0
+        self.total_cost = 0
+        self.model_name = model_name
+        self.reasoning_effort = reasoning_effort
+        self.base_url = base_url
+        if "ollama" in model_name and not base_url:
+            self.base_url = "http://localhost:11434"
+
+    def messages_for(self, text: str) -> list[dict]:
+        return [{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": text}]
+
+    def preprocess(self, text: str) -> str:
+        messages = self.messages_for(text)
+        response = completion(
+            messages=messages,
+            model=self.model_name,
+            reasoning_effort=self.reasoning_effort,
+            api_base=self.base_url,
+        )
+        self.total_input_tokens += response.usage.prompt_tokens
+        self.total_output_tokens += response.usage.completion_tokens
+        self.total_cost += response._hidden_params["response_cost"]
+        return response.choices[0].message.content

_hf_deploy/agents/scanner_agent.py

@@ -0,0 +1,176 @@
+import json
+import os
+import re
+from typing import Optional, List
+
+from groq import BadRequestError, Groq
+
+from agents.deals import ScrapedDeal, DealSelection
+from agents.agent import Agent
+from free_config import GROQ_MODEL
+
+
+class ScannerAgent(Agent):
+    MAX_DEALS_PER_REQUEST = 15
+
+    JSON_FORMAT_HINT = (
+        '\n\nRespond with JSON only, using this shape: '
+        '{"deals": [{"product_description": "...", "price": 99.99, "url": "https://..."}]}'
+        '\nThe JSON must be valid: no double-quote characters inside product_description '
+        '(write "6.9 inches" instead of 6.9"). No trailing commas. '
+        'Close the deals array with a single ] and the object with a single }.'
+    )
+
+    SYSTEM_PROMPT = """You identify and summarize the 5 most detailed deals from a list, by selecting deals that have the most detailed, high quality description and the most clear price.
+    You should provide the price as a number derived from the description. If the price of a deal isn't clear, do not include that deal in your response.
+    Most important is that you respond with the 5 deals that have the most detailed product description with price. It's not important to mention the terms of the deal; most important is a thorough description of the product.
+    Be careful with products that are described as "$XXX off" or "reduced by $XXX" - this isn't the actual price of the product. Only respond with products when you are highly confident about the price.
+    Never use the double-quote character inside product_description text. Spell out inch measurements as words, e.g. "55 inches" not 55".
+    """
+
+    USER_PROMPT_PREFIX = """Respond with the most promising 5 deals from this list, selecting those which have the most detailed, high quality product description and a clear price that is greater than 0.
+    You should rephrase the description to be a summary of the product itself, not the terms of the deal.
+    Remember to respond with a short paragraph of text in the product_description field for each of the 5 items that you select.
+    Be careful with products that are described as "$XXX off" or "reduced by $XXX" - this isn't the actual price of the product. Only respond with products when you are highly confident about the price.
+
+    Deals:
+
+    """
+
+    USER_PROMPT_SUFFIX = "\n\nInclude exactly 5 deals, no more."
+
+    name = "Scanner Agent"
+    color = Agent.CYAN
+
+    def __init__(self):
+        self.log("Scanner Agent is initializing")
+        self.client = Groq(api_key=os.environ["GROQ_API_KEY"])
+        self.model = GROQ_MODEL
+        self.log(f"Scanner Agent is ready (Groq / {self.model})")
+
+    def fetch_deals(self, memory) -> List[ScrapedDeal]:
+        """
+        Look up deals published on RSS feeds
+        Return any new deals that are not already in the memory provided
+        """
+        self.log("Scanner Agent is about to fetch deals from RSS feed")
+        urls = [opp.deal.url for opp in memory]
+        scraped = ScrapedDeal.fetch()
+        result = [scrape for scrape in scraped if scrape.url not in urls]
+        self.log(f"Scanner Agent received {len(result)} deals not already scraped")
+        return result
+
+    def make_user_prompt(self, scraped) -> str:
+        """
+        Create a user prompt based on the scraped deals provided
+        """
+        user_prompt = self.USER_PROMPT_PREFIX
+        user_prompt += "\n\n".join(
+            [scrape.describe() for scrape in scraped[: self.MAX_DEALS_PER_REQUEST]]
+        )
+        user_prompt += self.USER_PROMPT_SUFFIX
+        return user_prompt
+
+    @staticmethod
+    def _repair_deals_json(text: str) -> str:
+        text = text.strip()
+        text = re.sub(r'(\d+(?:\.\d+)?)"(\s+(?=[a-zA-Z0-9]))', r"\1 inches\2", text)
+        text = re.sub(r'("url"\s*:\s*"[^"]*")\s*\]', r"\1\n      }", text)
+        text = re.sub(
+            r'("url"\s*:\s*"[^"]*")\s*\}\s*\n\s*\]\s*\n\s*\}\}',
+            r"\1\n      }\n  ]\n}",
+            text,
+        )
+        text = re.sub(r"(\])\s*\]\s*\}\s*\}", r"\1}", text)
+        text = re.sub(r"(\])\s*\]\s*\}", r"\1}", text)
+        text = re.sub(r"\}\s*\}\s*$", r"}", text)
+        return text
+
+    def _parse_deals_json(self, content: str) -> DealSelection:
+        last_error = None
+        for candidate in (content, self._repair_deals_json(content)):
+            try:
+                result = DealSelection.model_validate(json.loads(candidate))
+                result.deals = [deal for deal in result.deals if deal.price > 0]
+                return result
+            except (json.JSONDecodeError, ValueError) as exc:
+                last_error = exc
+        raise ValueError(f"Could not parse deals JSON: {last_error}")
+
+    @staticmethod
+    def _extract_failed_generation(exc: BadRequestError) -> Optional[str]:
+        body = getattr(exc, "body", None)
+        if isinstance(body, dict):
+            return body.get("error", {}).get("failed_generation")
+        return None
+
+    def _call_groq(self, user_prompt: str) -> DealSelection:
+        messages = [
+            {"role": "system", "content": self.SYSTEM_PROMPT + self.JSON_FORMAT_HINT},
+            {"role": "user", "content": user_prompt},
+        ]
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                response_format={"type": "json_object"},
+                temperature=0,
+            )
+            return self._parse_deals_json(response.choices[0].message.content)
+        except BadRequestError as exc:
+            failed = self._extract_failed_generation(exc)
+            if failed:
+                self.log("Scanner Agent repairing malformed JSON from Groq response")
+                return self._parse_deals_json(failed)
+            raise
+
+    def scan(self, memory: List[str] = []) -> Optional[DealSelection]:
+        """
+        Call Groq to provide a high potential list of deals with good descriptions and prices
+        :param memory: a list of URLs representing deals already raised
+        :return: a selection of good deals, or None if there aren't any
+        """
+        scraped = self.fetch_deals(memory)
+        if not scraped:
+            return None
+        user_prompt = self.make_user_prompt(scraped)
+        self.log(f"Scanner Agent is calling Groq ({self.model})")
+        try:
+            result = self._call_groq(user_prompt)
+        except Exception as exc:
+            self.log(f"Scanner Agent failed to parse Groq response: {exc}")
+            return None
+        self.log(
+            f"Scanner Agent received {len(result.deals)} selected deals with price>0 from Groq"
+        )
+        return result
+
+    def test_scan(self, memory: List[str] = []) -> Optional[DealSelection]:
+        """
+        Return a test DealSelection, to be used during testing
+        """
+        results = {
+            "deals": [
+                {
+                    "product_description": "The Hisense R6 Series 55R6030N is a 55-inch 4K UHD Roku Smart TV that offers stunning picture quality with 3840x2160 resolution. It features Dolby Vision HDR and HDR10 compatibility, ensuring a vibrant and dynamic viewing experience. The TV runs on Roku's operating system, allowing easy access to streaming services and voice control compatibility with Google Assistant and Alexa. With three HDMI ports available, connecting multiple devices is simple and efficient.",
+                    "price": 178,
+                    "url": "https://www.dealnews.com/products/Hisense/Hisense-R6-Series-55-R6030-N-55-4-K-UHD-Roku-Smart-TV/484824.html?iref=rss-c142",
+                },
+                {
+                    "product_description": "The Poly Studio P21 is a 21.5-inch LED personal meeting display designed specifically for remote work and video conferencing. With a native resolution of 1080p, it provides crystal-clear video quality, featuring a privacy shutter and stereo speakers. This display includes a 1080p webcam with manual pan, tilt, and zoom control, along with an ambient light sensor to adjust the vanity lighting as needed. It also supports 5W wireless charging for mobile devices, making it an all-in-one solution for home offices.",
+                    "price": 30,
+                    "url": "https://www.dealnews.com/products/Poly-Studio-P21-21-5-1080-p-LED-Personal-Meeting-Display/378335.html?iref=rss-c39",
+                },
+                {
+                    "product_description": "The Lenovo IdeaPad Slim 5 laptop is powered by a 7th generation AMD Ryzen 5 8645HS 6-core CPU, offering efficient performance for multitasking and demanding applications. It features a 16-inch touch display with a resolution of 1920x1080, ensuring bright and vivid visuals. Accompanied by 16GB of RAM and a 512GB SSD, the laptop provides ample speed and storage for all your files. This model is designed to handle everyday tasks with ease while delivering an enjoyable user experience.",
+                    "price": 446,
+                    "url": "https://www.dealnews.com/products/Lenovo/Lenovo-Idea-Pad-Slim-5-7-th-Gen-Ryzen-5-16-Touch-Laptop/485068.html?iref=rss-c39",
+                },
+                {
+                    "product_description": "The Dell G15 gaming laptop is equipped with a 6th-generation AMD Ryzen 5 7640HS 6-Core CPU, providing powerful performance for gaming and content creation. It features a 15.6-inch 1080p display with a 120Hz refresh rate, allowing for smooth and responsive gameplay. With 16GB of RAM and a substantial 1TB NVMe M.2 SSD, this laptop ensures speedy performance and plenty of storage for games and applications. Additionally, it includes the Nvidia GeForce RTX 3050 GPU for enhanced graphics and gaming experiences.",
+                    "price": 650,
+                    "url": "https://www.dealnews.com/products/Dell/Dell-G15-Ryzen-5-15-6-Gaming-Laptop-w-Nvidia-RTX-3050/485067.html?iref=rss-c39",
+                },
+            ]
+        }
+        return DealSelection(**results)

_hf_deploy/agents/specialist_agent.py

@@ -0,0 +1,90 @@
+import os
+import re
+
+from agents.agent import Agent
+from free_config import GROQ_MODEL, USE_MODAL_SPECIALIST
+
+QUESTION = "What does this cost to the nearest dollar?"
+PREFIX = "Price is $"
+
+
+class SpecialistAgent(Agent):
+    """
+    Prices products using either:
+    1. Fine-tuned Llama on Modal (best quality, uses GPU credits), or
+    2. Groq fallback (free — same prompt format as the fine-tuned model)
+
+    Set USE_MODAL_SPECIALIST=true only if you have Modal credits to spare.
+    """
+
+    name = "Specialist Agent"
+    color = Agent.RED
+
+    def __init__(self):
+        self.pricer = None
+        self.groq_client = None
+        self.mode = "off"
+        self.model = GROQ_MODEL
+
+        if USE_MODAL_SPECIALIST:
+            self._try_modal()
+
+        if self.mode == "off" and os.getenv("GROQ_API_KEY"):
+            from groq import Groq
+
+            self.groq_client = Groq(api_key=os.environ["GROQ_API_KEY"])
+            self.mode = "groq"
+            self.log(f"Specialist Agent using Groq fallback ({self.model}) — no Modal GPU needed")
+
+        if self.mode == "off":
+            self.log("Specialist Agent disabled — ensemble will use Frontier + Neural Network only")
+
+    def _try_modal(self):
+        try:
+            import modal
+
+            self.log("Specialist Agent is initializing - connecting to Modal")
+            Pricer = modal.Cls.from_name("pricer-service", "Pricer")
+            self.pricer = Pricer()
+            self.mode = "modal"
+            self.log("Specialist Agent connected to Modal pricer-service")
+        except Exception as exc:
+            self.log(f"Modal unavailable ({exc}) — will try Groq fallback if configured")
+
+    @property
+    def available(self) -> bool:
+        return self.mode != "off"
+
+    @staticmethod
+    def _parse_price(text: str) -> float:
+        if PREFIX in text:
+            text = text.split(PREFIX, 1)[1]
+        text = text.replace("$", "").replace(",", "")
+        match = re.search(r"[-+]?\d*\.\d+|\d+", text)
+        return float(match.group()) if match else 0.0
+
+    def _price_with_groq(self, description: str) -> float:
+        prompt = f"{QUESTION}\n\n{description}\n\n{PREFIX}"
+        response = self.groq_client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0,
+            max_tokens=8,
+        )
+        reply = response.choices[0].message.content or ""
+        return self._parse_price(reply)
+
+    def price(self, description: str) -> float:
+        if self.mode == "modal":
+            self.log("Specialist Agent is calling remote fine-tuned model on Modal")
+            result = self.pricer.price.remote(description)
+            self.log(f"Specialist Agent completed - predicting ${result:.2f}")
+            return result
+
+        if self.mode == "groq":
+            self.log(f"Specialist Agent is calling Groq ({self.model})")
+            result = self._price_with_groq(description)
+            self.log(f"Specialist Agent completed - predicting ${result:.2f}")
+            return result
+
+        return 0.0

_hf_deploy/app.py

@@ -0,0 +1,25 @@
+"""
+Hugging Face Spaces entry point.
+
+Upload the entire week8/ folder into the Space repo root (this file becomes app.py),
+or copy week8/* into the Space and rename/move as needed.
+
+Required Space secrets: GROQ_API_KEY, HF_TOKEN, USE_MODAL_SPECIALIST=false
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# When week8 is the Space root, agents/ and deal_agent_framework.py are siblings.
+ROOT = Path(__file__).resolve().parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+os.environ.setdefault("GRADIO_SERVER_NAME", "0.0.0.0")
+os.environ.setdefault("PRICER_PREPROCESSOR_MODEL", "groq/llama-3.1-8b-instant")
+
+from price_is_right import App
+
+if __name__ == "__main__":
+    App().run()

_hf_deploy/deal_agent_framework.py

@@ -0,0 +1,119 @@
+import os
+import sys
+import logging
+import json
+from typing import List
+from dotenv import load_dotenv
+import chromadb
+from agents.planning_agent import PlanningAgent
+from agents.deals import Opportunity
+from sklearn.manifold import TSNE
+import numpy as np
+
+load_dotenv(override=True)
+
+# Colors for logging
+BG_BLUE = "\033[44m"
+WHITE = "\033[37m"
+RESET = "\033[0m"
+
+# Colors for plot
+CATEGORIES = [
+    "Appliances",
+    "Automotive",
+    "Cell_Phones_and_Accessories",
+    "Electronics",
+    "Musical_Instruments",
+    "Office_Products",
+    "Tools_and_Home_Improvement",
+    "Toys_and_Games",
+]
+COLORS = ["red", "blue", "brown", "orange", "yellow", "green", "purple", "cyan"]
+
+
+def init_logging():
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(logging.INFO)
+    formatter = logging.Formatter(
+        "[%(asctime)s] [Agents] [%(levelname)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S %z",
+    )
+    handler.setFormatter(formatter)
+    root.addHandler(handler)
+
+
+class DealAgentFramework:
+    DB = "products_vectorstore"
+    MEMORY_FILENAME = "memory.json"
+
+    def __init__(self):
+        init_logging()
+        client = chromadb.PersistentClient(path=self.DB)
+        self.memory = self.read_memory()
+        self.collection = client.get_or_create_collection("products")
+        self.planner = None
+
+    def init_agents_as_needed(self):
+        if not self.planner:
+            self.log("Initializing Agent Framework")
+            self.planner = PlanningAgent(self.collection)
+            self.log("Agent Framework is ready")
+
+    def read_memory(self) -> List[Opportunity]:
+        if os.path.exists(self.MEMORY_FILENAME):
+            with open(self.MEMORY_FILENAME, "r") as file:
+                data = json.load(file)
+            opportunities = [Opportunity(**item) for item in data]
+            return opportunities
+        return []
+
+    def write_memory(self) -> None:
+        data = [opportunity.model_dump() for opportunity in self.memory]
+        with open(self.MEMORY_FILENAME, "w") as file:
+            json.dump(data, file, indent=2)
+
+    @classmethod
+    def reset_memory(cls) -> None:
+        data = []
+        if os.path.exists(cls.MEMORY_FILENAME):
+            with open(cls.MEMORY_FILENAME, "r") as file:
+                data = json.load(file)
+        truncated = data[:2]
+        with open(cls.MEMORY_FILENAME, "w") as file:
+            json.dump(truncated, file, indent=2)
+
+    def log(self, message: str):
+        text = BG_BLUE + WHITE + "[Agent Framework] " + message + RESET
+        logging.info(text)
+
+    def run(self) -> List[Opportunity]:
+        self.init_agents_as_needed()
+        logging.info("Kicking off Planning Agent")
+        result = self.planner.plan(memory=self.memory)
+        logging.info(f"Planning Agent has completed and returned: {result}")
+        if result:
+            self.memory.append(result)
+            self.write_memory()
+        return self.memory
+
+    @classmethod
+    def get_plot_data(cls, max_datapoints=2000):
+        client = chromadb.PersistentClient(path=cls.DB)
+        collection = client.get_or_create_collection("products")
+        result = collection.get(
+            include=["embeddings", "documents", "metadatas"], limit=max_datapoints
+        )
+        vectors = np.array(result["embeddings"])
+        documents = result["documents"]
+        categories = [metadata["category"] for metadata in result["metadatas"]]
+        colors = [COLORS[CATEGORIES.index(c)] for c in categories]
+        tsne = TSNE(n_components=3, random_state=42, n_jobs=-1)
+        reduced_vectors = tsne.fit_transform(vectors)
+        return documents, reduced_vectors, colors
+
+
+if __name__ == "__main__":
+    DealAgentFramework().run()

_hf_deploy/env_utils.py

@@ -0,0 +1,14 @@
+"""Load .env from repo root or week8 folder."""
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+WEEK8_DIR = Path(__file__).resolve().parent
+REPO_ROOT = WEEK8_DIR.parent
+
+
+def load_project_env() -> None:
+    for path in (REPO_ROOT / ".env", WEEK8_DIR / ".env"):
+        if path.exists():
+            load_dotenv(path, override=True)