My Dialog

workflow_example_for_solvers.ipynb

{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Notes For Solvers\n", "\n", "Anything that is labeled with **For Solvers** are notes for users of the Solveit Platform. Everything else in this gist is left as a reference, or example, to represent an idea or comment in the following general notes."]}, {"cell_type": "markdown", "metadata": {}, "source": ["### **For Solvers:** \n", "\n", "Here are some thoughts I'd like to share and notes I've collected on working in the solveit platform. I hope they may be helpful or useful to someone else.\n", "\n", "1. Conceptually, I split the dialogue into two parts:\n", "\n", "    - Top Half - Doc Zone - for adding notes, docs and creating or storing artifacts\n", "    - Bottom Half - Dev Zone - for actual development and discussion\n", "    - Both get developed concurrently, but with different processes and mini-objectives\n", "\n", "1. Doc Zone:\n", "\n", "    - Objective - Get the Dev Zone outputs to be devlivering results as effectively as possible\n", "    - Be quick to bring context info in, but even quicker to alter it by condensing, refactoring, and making cells invisible, depending on what is the current focus in the Dev Zone\n", "    - I find that too much context in the dialogue (even if I find it relevant) can cause the quality of output results to be somewhat reduced\n", "\n", "1. Dev Zone:\n", "\n", "    - Objective - Perform small iterative development cycles to reach testing points quickly\n", "    - Usually begins with pulling the current repo I am working on into an artifact prompt using dollar-backticks (and using the ghapi package)\n", "    - Also I put one last final reminder (hopefully) of what the objective of the notebook is to keep the iterative cycles of work done in Dev Zone aligned with the bigger goals at hand\n", "    - Dev Cycle - Code down; Copy out; Test locally; Debug if necessary; Test again if necessary; Commit/Push; Reduce/Delete up (clean up); Pull updated code into solveit; Repeat;\n", "\n", "1. Syncing Envs\n", "\n", "    - While solveit is far and away the best development environment, it's still limited by what can be tested there in depth, so I frequently copy code into my local environment for testing purposes. \n", "    - This back-and-forth between solveit and my local environment creates a powerful feedback loop. Each sync represents a complete thought or feature implementation.\n", "    - Example code for this step is contained in this gist.\n", "\n", "1. Dollar Backticks: \n", "\n", "    - I find these to be the best way for getting code into context (at least for reasons mentioned above in the Doc Zone explanation)\n", "    - It also seems to help the output follow my personal coding styles more closely, depending on the exact repo, without as much explicit prompting necessary\n", "\n", "1. Working Analogies:\n", "\n", "    - I have two pieces of visual imagery I tend to think about while working in solveit\n", "    - They help me to follow the solveit style of development and keep from vibing too hard (hackathons excepted)\n", "    - They both apply primarily to working in the Dev Zone and its objective\n", "\n", "1. Accordian Flow:\n", "\n", "    - The idea here is to imagine the dialogue expanding and contracting like an accordian. The most important point is the that the accordian must contract!\n", "    - The accordian expands to get a result over multiple working cells, arrives at a testing/resting point, then contracts while cleaning up the working area. \n", "    - This expansion-contraction rhythm helps me maintain focus by forcing regular reflection points, preventing scope creep, and keeping my dialogue history manageable. \n", "    - Each contraction creates a natural checkpoint where I can assess progress against my objectives before starting the next development cycle.\n", "\n", "1. Mountain-climbing coding:\n", "\n", "    - This one is helpful for working on a GitHub repo and keeping different environments synced.\n", "    - The idea is to imagine the Dev Cycle process (noted above) mapping onto a mountain climbing process.\n", "    - Solveit provides us with a pair of MI4 sticky gloves for climbing, so it's easy to feel over-confident.\n", "    - Just as a climber secures multiple anchor points, these regular commits create safe points to return to, reducing the risk of losing significant work and making my development process more resilient to unexpected issues.\n", "\n", "1. Prompt mode:\n", "\n", "    - Learning mode gets it done right. \n", "    - After using standard most frequently during my early days on the platform and then opting for concise once it was released, I have most recently started using the learning mode almost exlcusively. \n", "    - It really does help for staying in control during a development cycle. It seems to take a larger number of prompts, but it actually reduces the number overall on average becasue it's harder to go off-the-rails while you are taking smaller steps. \n", "    - Having to get back on track or redo work are hidden costs that are obviously best avoided but that in itself is also easier said than done in practice."]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Example Dialogue \n", "\n", "**For Solvers:** This dialogue has been reduced for demo purposes. The complete dialogue is in a complimentary gist. The Doc Zone begins immediately below this cell."]}, {"cell_type": "markdown", "metadata": {}, "source": ["I'm taking part in a hackathon today. Here is the relavent information.\n", "\n", "    # {Tech: Berlin} AI Hackathon #3\n", "\n", "    ## Hackathon Track\n", "\n", "    ### **\u2615\ufe0f Track 4: Next Level Coffee - Brewing Better Coffee with AI**\n", "\n", "    Coffee is personal, complex, and increasingly powered by data. At Next Level\n", "    Coffee(NLC), we\u2019ve built nunc.\u2014a connected espresso machine and grinder that\n", "    captures detailed IoT data from every single shot brewed and bean ground.\n", "\n", "    In this track, you\u2019ll work with real data from nunc. to either optimize the brewing\n", "    process or personalize the coffee experience through AI. Your solution should\n", "    show how technology can elevate the art and science of coffee.\n", "\n", "    **Personalized Coffee Recommendation Agent**\n", "\n", "    What if your coffee machine knew your taste better than you do?\n", "\n", "    Build an AI agent that takes a user\u2019s preferences\u2014and deduces what kind of\n", "    coffee they\u2019d love. No need for fancy cupping notes or flavor wheel terms. Just\n", "    real talk: \u201cI like fruity coffee but not too sour,\u201d or \u201cI want something smooth to\n", "    drink with milk.\u201d\n", "    The agent should:\n", "\n", "    - Ask thoughtful, simple questions\n", "    - Translate human preferences into coffee parameters\n", "    - Recommend coffees from the nunc. lineup that match the user\u2019s profile\n", "\n", "    **Regardless of which use case you choose**, your team must also analyze the\n", "    provided nunc. dataset and surface **at least 3 actionable insights** that could\n", "    improve:\n", "\n", "    - The **engineering** of the nunc. machine itself (e.g., hardware, sensors,\n", "    algorithms), or\n", "    - The **brewing experience** for users (e.g., consistency, usability,\n", "    personalization)\n", "\n", "    We\u2019re looking for curious minds who dig deep and bring fresh ideas to the\n", "    surface.\n", "\n", "**For Solvers:** Just some intro notes, to set the stage. (above 1 and below 2)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Here some more info on our selected challenge:\n", "\n", "    Use Case 2: Instant Dial-In - Scan Your Coffee, Personalize Your Flavor\n", "    Can we dial in the perfect espresso just by looking at the coffee? This use case is especially\n", "    designed for coffee nerds. Your task:\n", "    Build a model or AI agent that uses visual input (like coffee bag photos, roast level, origin, and\n", "    tasting notes) and combines it with knowledge of coffee extraction science to recommend the\n", "    ideal espresso shot parameters for a new coffee.\n", "    The goal? Enable users to simply scan or upload a photo* of the coffee and instantly receive\n", "    personalized dial-in recommendations\u2014no guesswork, no waste.\n", "    In addition to image and coffee data, the model should also ask the user for their desired\n", "    flavor experience\u2014for example: balanced, fruity, bold, sweet, or chocolatey. Based on both\n", "    the realistic potential of the coffee (roast level, processing, origin) and the user\u2019s input, the\n", "    model should adjust the recipe accordingly.\n", "    Your model should determine the shot based on the following parameters:\n", "    \u2022 Flow or pressure control of the shot \u2014 recommend a target flow rate or pressure profile\n", "    \u2022 Brewing temperature\n", "    \u2022 Grind setting, using 120 \u03bcm of the \u201cBAR ITALIA\u201d as the reference point\n", "    \u2022 Brew ratio \u2014 the ratio of ground coffee to total water used\n", "    Your solution should integrate effortlessly into the nunc. ecosystem, combining visual\n", "    recognition, taste profiling, and extraction physics to deliver fast, high-fidelity recipes tailored\n", "    to both the coffee and the drinker\u2014all with a single scan and a tap."]}, {"cell_type": "markdown", "metadata": {}, "source": ["Here are the collective notes from our team:\n", "\n", "    Notes\n", "    Chosen problem: use case 2\n", "    Input is image, model detects coffee brand, according to detection results get brew parameters based on available coffee brand database, \n", "    mapping from user preferences to grinding and brewing parameters\n", "    mapping from grind and brew parameters to coffee tastes\n", "    4 key attributes from coffee package\n", "    country/origin\n", "    roast level (med, dark, light)\n", "    variety (arabica, robusta)\n", "    process (natural, washed)\n", "    Others (harder to obtain or less important)\n", "    Elevation \n", "    Roast Date\n", "    Uer input:\n", "    What kind of drink? (espresso, americano)\n", "    Intensity (strong, med, mild)\n", "\n", "    Questions\n", "    what kinds of actionable insights shall we get from the data by analysing it? What are to expected, as an example\n", "    how to link eventID between grinding and brewing\n", "    the mapping from brand to grind and brew process/params \n", "    Is there any kind of constraint on the type or form of user input for part 2?\n", "    what taste profiles can be affected by brewing conditions?\n", "    What is affected mainly by the bean \n", "\n", "    Internal Questions\n", "    What affects the taste profile and how?\n", "    How does the bean/roast/blend/color affect the taste profile?\n", "    How do the grind/brew/consumer-environment and machine settings affect the taste profile?\n", "    How does the latter affect the former?\n", "\n", "    Solution Components\n", "    UI Input: Formly\n", "    Make a simple UI and record data to google sheets\n", "    input 4 user arguments\n", "    strong-light\n", "    fruity-bold\n", "    sour-bitter\n", "    Read input data from google sheet,\n", "    OCR (Image processing)\n", "    Extract structured data (json: simple coffee profile) from coffee package image (png), four values\n", "    country/origin\n", "    use 7 largest regions\n", "    three regions/groups:\n", "    center, south america\n", "    aisa, pacific\n", "    africa\n", "    roast level (dark, med-dark, med-light, light)\n", "    variety (arabica, robusta)\n", "    process (natural, washed, honey)\n", "    Map: coffee profile to machine parameters\n", "    Analyze machine parameter data\n", "    Map: Taste Profiles to Machine parameters\n", "    10 taste profiles for machines\n", "    LLM summary for final \n", "    Prompt needed"]}, {"cell_type": "markdown", "metadata": {}, "source": ["I want to make FastHTML app that can become the foundation for this solution.\n", "\n", "1. I am quite experienced with HTML, CSS and javascript.\n", "2. I want a simple interface that is fast to implemnt, but still looks nice enought for a demo in a hackathon\n", "3. No specific design in mind.\n", "1. I want to use anything from franken-ui, monster-ui, or tailwind.\n", "2. Let's start with a basic html template. The functionality will be completed by my teammates.\n", "\n", "**For Solvers:** This was generated from the typical exploratory chat in learning mode, and then summarizing into the small note."]}, {"cell_type": "markdown", "metadata": {}, "source": ["Fast HTML Monster UI Starter Template\n", "\n", "**For Solvers:** This was used with the search functionality to pull relavent doc-notes into the context. They have been deleted from this notebook for faster reading."]}, {"cell_type": "markdown", "metadata": {}, "source": ["### For Solvers\n", "\n", "1. These functions use the ghapi package to recursively find and pull all files of a given repo into a dictionary that can be sent to claude as an artifact using dollar backticks."]}, {"cell_type": "code", "metadata": {}, "source": ["def create_github_client(token_env_var='GITHUB_TOKEN'):\n", "    \"\"\"Create a GitHub API client with proper authentication.\"\"\"\n", "    token = os.environ.get(token_env_var)\n", "    if not token:\n", "        print(f\"Warning: {token_env_var} not found, running unauthenticated\")\n", "    return GhApi(token=token)\n", "\n", "\n", "def get_file_content(api, owner, repo, path, max_size=1000000):\n", "    \"\"\"Get content of a file with error handling and size limits.\"\"\"\n", "    try:\n", "        content = api.repos.get_content(owner, repo, path)\n", "        if content.size <= max_size:\n", "            decoded_content = base64.b64decode(content.content).decode('utf-8')\n", "            return decoded_content\n", "        else:\n", "            print(f\"Skipped large file: {path} ({content.size} bytes)\")\n", "            return None\n", "    except Exception as e:\n", "        print(f\"Error fetching {path}: {e}\")\n", "        return None\n", "\n", "\n", "def analyze_repository(api, owner, repo_name, fetch_readme=True):\n", "    \"\"\"Analyze GitHub repository structure with configurable options.\"\"\"\n", "    try:\n", "        repo = api.repos.get(owner, repo_name)\n", "        contents = api.repos.get_content(owner, repo_name, \"\")\n", "        \n", "        files = [f.name for f in contents if f.type == \"file\"]\n", "        dirs = [d.name for d in contents if d.type == \"dir\"]\n", "        \n", "        readme = None\n", "        if fetch_readme and 'README.md' in files:\n", "            readme = get_file_content(api, owner, repo_name, \"README.md\")\n", "        \n", "        return {\n", "            'repo': repo,\n", "            'name': repo.name,\n", "            'description': repo.description,\n", "            'stars': repo.stargazers_count,\n", "            'forks': repo.forks_count,\n", "            'updated_at': repo.updated_at,\n", "            'files': files,\n", "            'directories': dirs,\n", "            'readme': readme,\n", "            'license': repo.license.name if repo.license else None,\n", "            'api': api,\n", "            'owner': owner\n", "        }\n", "    except Exception as e:\n", "        print(f\"Error analyzing repository {owner}/{repo_name}: {e}\")\n", "        return None\n", "\n", "\n", "def extract_files(api, owner, repo, paths=None, patterns=None, max_files=10, \n", "                 print_content=False, content_max=10000):\n", "    \"\"\"Extract files from a repository using paths or patterns.\"\"\"\n", "    if not paths and not patterns:\n", "        patterns = ['example', 'tutorial', 'quickstart', 'README']\n", "    \n", "    file_contents = {}\n", "    \n", "    # If specific paths are provided, use them directly\n", "    if paths:\n", "        for path in paths[:max_files]:\n", "            content = get_file_content(api, owner, repo, path)\n", "            if content:\n", "                file_contents[path] = content\n", "                if print_content:\n", "                    print(f\"\\n=== {path} ===\\n\")\n", "                    print(content[:content_max] + \"...\" if len(content) > content_max else content)\n", "        return file_contents\n", "    \n", "    # Otherwise search by patterns\n", "    try:\n", "        all_files = []\n", "        contents = api.repos.get_content(owner, repo, \"\")\n", "        \n", "        for item in contents:\n", "            if item.type == \"file\" and any(p.lower() in item.name.lower() for p in patterns):\n", "                all_files.append(item.path)\n", "        \n", "        all_files = all_files[:max_files]\n", "        \n", "        for path in all_files:\n", "            content = get_file_content(api, owner, repo, path)\n", "            if content:\n", "                file_contents[path] = content\n", "                if print_content:\n", "                    print(f\"\\n=== {path} ===\\n\")\n", "                    print(content[:content_max] + \"...\" if len(content) > content_max else content)\n", "                    \n", "        return file_contents\n", "    except Exception as e:\n", "        print(f\"Error extracting files: {e}\")\n", "        return file_contents\n", "\n", "\n", "def collect_files_recursively(api, owner, repo, max_files=500, max_depth=5, \n", "                             patterns=None, dir_path=\"\"):\n", "    \"\"\"Recursively collect files from a repository with proper depth traversal.\"\"\"\n", "    all_files = []\n", "    dirs_to_check = [dir_path]\n", "    visited_dirs = set()\n", "    \n", "    while dirs_to_check and len(all_files) < max_files:\n", "        current_dir = dirs_to_check.pop(0)\n", "        \n", "        # Skip if we've already visited this directory\n", "        if current_dir in visited_dirs:\n", "            continue\n", "            \n", "        visited_dirs.add(current_dir)\n", "        \n", "        try:\n", "            contents = api.repos.get_content(owner, repo, current_dir)\n", "            \n", "            # Process each item in the directory\n", "            for item in contents:\n", "                path = f\"{current_dir}/{item.name}\".lstrip('/')\n", "                \n", "                if item.type == \"file\":\n", "                    if not patterns or any(p.lower() in path.lower() for p in patterns):\n", "                        all_files.append(path)\n", "                elif item.type == \"dir\":\n", "                    # Only add directory if we haven't reached max depth\n", "                    depth = path.count('/') + 1\n", "                    if depth <= max_depth:\n", "                        dirs_to_check.append(path)\n", "                        \n", "        except Exception as e:\n", "            print(f\"Error accessing {current_dir}: {e}\")\n", "    \n", "    return all_files\n", "\n", "\n", "def fetch_multiple_files(api, owner, repo, file_list, max_size=1e7):\n", "    result = {}\n", "    \n", "    for file_path in file_list:\n", "        content = get_file_content(api, owner, repo, file_path, max_size)\n", "        result[file_path] = content\n", "    \n", "    return result"], "outputs": [], "execution_count": null}, {"cell_type": "markdown", "metadata": {}, "source": ["#### Base Repo"]}, {"cell_type": "code", "metadata": {}, "source": ["import os\n", "from ghapi.core import GhApi\n", "import base64\n", "\n", "def get_repo_contents(repo_author, repo_name, token='GITHUB_PERSONAL_TOKEN'):\n", "    # First, create the GitHub client\n", "    api = create_github_client(token_env_var=token)\n", "\n", "    # Analyze the repository structure\n", "    repo_info = analyze_repository(api, repo_author, repo_name)\n", "\n", "    # Print basic repository information\n", "    print(f\"Repository: {repo_info['name']}\")\n", "    print(f\"Description: {repo_info['description']}\")\n", "    print(f\"Stars: {repo_info['stars']}\")\n", "    print(f\"Files in root: {repo_info['files']}\")\n", "    print(f\"Directories: {repo_info['directories']}\")\n", "\n", "    # Recursively collect Python files\n", "    get_files = collect_files_recursively(\n", "        api,\n", "        repo_author,\n", "        repo_name,\n", "        max_files=25,\n", "        max_depth=5\n", "    )\n", "\n", "    return fetch_multiple_files(api, repo_author, repo_name, get_files)"], "outputs": [], "execution_count": null}, {"cell_type": "code", "metadata": {}, "source": ["repo_contents = get_repo_contents('digispect-intel', 'nunc_perfect_cup_of_coffee')"], "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Repository: nunc_perfect_cup_of_coffee\n", "Description: None\n", "Stars: 1\n", "Files in root: ['.gitignore', 'README.md', 'main.py', 'requirements.txt', 'technical_documentation.md']\n", "Directories: ['insights', 'modules', 'static']\n", "Error fetching insights/cleaned_coffee_data.xlsx: 'utf-8' codec can't decode byte 0x86 in position 12: invalid start byte\n", "Error fetching insights/coffee_visualizations/brewing_parameters.png: 'utf-8' codec can't decode byte 0x89 in position 0: invalid start byte\n", "Error fetching insights/coffee_visualizations/flavor_by_origin_heatmap.png: 'utf-8' codec can't decode byte 0x89 in position 0: invalid start byte\n", "Error fetching insights/coffee_visualizations/process_flavor_radar.png: 'utf-8' codec can't decode byte 0x89 in position 0: invalid start byte\n", "Error fetching insights/coffee_visualizations/roast_flavor_radar.png: 'utf-8' codec can't decode byte 0x89 in position 0: invalid start byte\n"]}], "execution_count": null}, {"cell_type": "markdown", "metadata": {}, "source": ["#### AI Agent Framework repo"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Here are some docs on ControlFlow\n", "\n", "Pydantic models\n", "\n", "**For Solvers** I just copied some text from the controlflow docs into this note. Removed for brevity."]}, {"cell_type": "markdown", "metadata": {}, "source": ["A reminder on our actual challenge: IMPORTANT!\n", "\n", "    Use Case 2: Instant Dial-In - Scan Your Coffee, Personalize Your Flavor\n", "    Can we dial in the perfect espresso just by looking at the coffee? This use case is especially\n", "    designed for coffee nerds. Your task:\n", "    Build a model or AI agent that uses visual input (like coffee bag photos, roast level, origin, and\n", "    tasting notes) and combines it with knowledge of coffee extraction science to recommend the\n", "    ideal espresso shot parameters for a new coffee.\n", "    The goal? Enable users to simply scan or upload a photo* of the coffee and instantly receive\n", "    personalized dial-in recommendations\u2014no guesswork, no waste.\n", "    In addition to image and coffee data, the model should also ask the user for their desired\n", "    flavor experience\u2014for example: balanced, fruity, bold, sweet, or chocolatey. Based on both\n", "    the realistic potential of the coffee (roast level, processing, origin) and the user\u2019s input, the\n", "    model should adjust the recipe accordingly.\n", "    Your model should determine the shot based on the following parameters:\n", "    \u2022 Flow or pressure control of the shot \u2014 recommend a target flow rate or pressure profile\n", "    \u2022 Brewing temperature\n", "    \u2022 Grind setting, using 120 \u03bcm of the \u201cBAR ITALIA\u201d as the reference point\n", "    \u2022 Brew ratio \u2014 the ratio of ground coffee to total water used\n", "    Your solution should integrate effortlessly into the nunc. ecosystem, combining visual\n", "    recognition, taste profiling, and extraction physics to deliver fast, high-fidelity recipes tailored\n", "    to both the coffee and the drinker\u2014all with a single scan and a tap.\n", "\n", "**For Solvers:** This was added to help keep the LLM on track, as the context is starting to get large, and the actual coding/work/development is about to begin."]}, {"cell_type": "markdown", "metadata": {}, "source": ["Here are some docs on Mistral Vision Models:\n", "\n", "**For Solvers:** Same as above I just copied text directly from the mistral docs into this note. Removed for brevity."]}, {"cell_type": "markdown", "metadata": {}, "source": ["**AI Prompt**\n", "\n", "Please provide me with a plan to improve the recommender module, based on the current $`repo_contents`."]}, {"cell_type": "markdown", "metadata": {}, "source": ["**AI Response**\n", "\n", "Please post on Discord that you got this error:\n", "Expecting value: line 2 column 1 (char 1)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["### For Solvers\n", "\n", "This is what I would call the start of the Dev Zone. The above prompt sends the repo_contents as a claude artifact and keeps the actual prompt context from becomming diluted."]}], "metadata": {"kernelspec": {"display_name": "python3", "language": "python", "name": "python3"}}, "nbformat": 4, "nbformat_minor": 4}