Harryky/improve study buddy agent

agents/manifests/study_buddy_agent.json

@@ -1,7 +1,7 @@
 {
   "id": "study_buddy",
   "name": "Study Buddy Agent",
-  "description": "Creates study plans, flashcards, and practice questions from your notes and topics.",
+  "description": "Turns your notes and topic into a timed study session with a study plan, flashcards, and practice questions.",
   "category": "Education",
   "creator": "AgentStore Team",
   "version": "1.0.0",
@@ -29,7 +29,7 @@
       "practice_questions": { "type": "array" }
     }
   },
-  "example_use_case": "Generate a 30-minute study session on machine learning basics using your class notes.",
+  "example_use_case": "Generate a 30-minute study session on machine learning basics using class notes and quick web references.",
   "example_prompts": [
     "Create a study plan for my calculus exam",
     "Make flashcards from my biology notes"

agents/runner/study_buddy_runner_design.md

@@ -0,0 +1,161 @@
+# Study Buddy Runner Design
+
+## Purpose
+
+Define how the Study Buddy Agent runner should simulate execution before building more complex logic. This design intentionally avoids real external APIs and does not require a real LLM.
+
+## Agent Chosen
+
+- Agent: Study Buddy Agent
+- Agent ID: `study_buddy`
+- Manifest: `agents/manifests/study_buddy_agent.json`
+- Required tools: `notes`, `web_search`
+
+## What the Runner Should Do
+
+The runner should take a user request such as:
+
+- "Create a study plan for my calculus exam"
+- "Make flashcards from my biology notes"
+
+Then it should simulate a study-planning workflow by:
+
+1. Reading the agent manifest.
+2. Extracting required tools.
+3. Building mock tool calls for `notes` and `web_search`.
+4. Generating a structured study plan.
+5. Producing flashcards and practice questions.
+6. Returning a simulated trace plus final response.
+
+## Input -> Tool -> Output Map
+
+| Agent | Required Tools | Mock Tool Output | Final Response |
+|------|----------------|------------------|----------------|
+| Study Buddy Agent | `notes`, `web_search` | Notes tool returns note snippets, topic keywords, and any requested note IDs. Web search returns short learning references or beginner-friendly examples. | A timed study plan, flashcards, practice questions, and a short session summary. |
+
+## Simulated Flow
+
+### 1. Receive user request
+- Read `topic`, `study_duration_minutes`, and optional `note_ids`.
+- Normalize missing values.
+- Default duration to 30 minutes if not provided.
+
+### 2. Identify required tools
+- Pull `tools_required` from the manifest.
+- For Study Buddy, the expected tools are:
+  - `notes`
+  - `web_search`
+
+### 3. Mock tool calls
+- `notes`:
+  - Simulate reading note content by note ID.
+  - If note IDs are missing, simulate a generic note lookup for the topic.
+- `web_search`:
+  - Simulate a few search results for the study topic.
+  - Return short snippets only, not live web content.
+
+### 4. Process results
+- Combine note snippets and search snippets.
+- Select the most relevant concepts.
+- Split the study session into review, recall, and practice segments.
+
+### 5. Generate final output
+- Build a study plan.
+- Create flashcards.
+- Create practice questions.
+- Summarize the session outcome.
+
+## Pseudocode
+
+```text
+function run_study_buddy(user_input):
+    load study buddy manifest
+    tools = manifest.tools_required
+    topic = user_input.topic or "requested topic"
+    duration = user_input.study_duration_minutes or 30
+    note_ids = user_input.note_ids or []
+
+    trace = []
+    trace.add(step 1: receive request)
+    trace.add(step 2: identify tools)
+
+    notes_result = mock_notes_read(note_ids, topic)
+    trace.add(step 3: mock notes tool call)
+
+    search_result = mock_web_search(topic)
+    trace.add(step 4: mock web search tool call)
+
+    combined_points = merge(notes_result, search_result)
+    study_plan = build_timed_plan(duration, combined_points)
+    flashcards = build_flashcards(combined_points)
+    practice_questions = build_practice_questions(combined_points)
+
+    final_output = {
+        study_plan,
+        flashcards,
+        practice_questions,
+        session_summary
+    }
+
+    trace.add(step 5: process results)
+    trace.add(step 6: generate final output)
+
+    return {
+        status: "simulated",
+        trace,
+        final_output
+    }
+```
+
+## TODO Comments for Implementation
+
+- TODO: Load the study buddy manifest from `agents/manifests/`.
+- TODO: Read `tools_required` and build one mock step per tool.
+- TODO: Simulate `notes` output using note IDs or topic keywords.
+- TODO: Simulate `web_search` output with canned search snippets.
+- TODO: Compose a deterministic study plan from the mock tool output.
+- TODO: Return a trace object with steps, intermediate results, and final output.
+- TODO: Keep the runner offline and deterministic.
+
+## Example Mock Outputs
+
+### Notes Tool
+
+```text
+Retrieved 2 class notes covering supervised learning, overfitting, and evaluation metrics.
+```
+
+### Web Search Tool
+
+```text
+Found 3 reference snippets for beginner-friendly examples and terminology.
+```
+
+### Final Response
+
+```json
+{
+  "agent_id": "study_buddy",
+  "status": "simulated",
+  "message": "Generated fallback simulated execution",
+  "trace": {
+    "run_id": "run_study_001",
+    "steps": []
+  },
+  "output": {
+    "study_plan": [],
+    "flashcards": [],
+    "practice_questions": [],
+    "session_summary": "Completed a simulated study session."
+  }
+}
+```
+
+## Acceptance Criteria
+
+- No real external APIs are called.
+- No real LLM is required.
+- The runner works fully offline with deterministic mock data.
+- The design clearly maps `study_buddy` to `notes` and `web_search`.
+- The design includes a trace, intermediate results, and a final response.
+- The design can be implemented without changing the agent manifest contract.

agents/traces/study_buddy_trace.json

@@ -0,0 +1,88 @@
+{
+  "agent_id": "study_buddy",
+  "run_id": "run_study_001",
+  "status": "simulated",
+  "started_at": "2026-06-16T08:00:00Z",
+  "completed_at": "2026-06-16T08:00:06Z",
+  "user_request": "Create a 30-minute study session on machine learning basics using my class notes.",
+  "steps": [
+    {
+      "step": 1,
+      "action": "Receive user request",
+      "details": "Parsed request: build a 30-minute study session for machine learning basics using provided notes"
+    },
+    {
+      "step": 2,
+      "action": "Identify required tools",
+      "details": "Agent manifest requires: notes, web_search"
+    },
+    {
+      "step": 3,
+      "action": "Call mock tool",
+      "tool": "notes",
+      "input": { "action": "read", "note_ids": ["ml_intro_01", "ml_intro_02"] },
+      "output_summary": "Retrieved 2 class notes covering supervised learning, overfitting, and evaluation metrics"
+    },
+    {
+      "step": 4,
+      "action": "Call mock tool",
+      "tool": "web_search",
+      "input": { "query": "machine learning basics study guide overfitting evaluation metrics" },
+      "output_summary": "Found 3 reference snippets for beginner-friendly examples and terminology"
+    },
+    {
+      "step": 5,
+      "action": "Process tool response",
+      "details": "Grouped note content into review, practice, and recall segments; selected key terms for flashcards"
+    },
+    {
+      "step": 6,
+      "action": "Generate final answer",
+      "details": "Produced a timed study plan with flashcards and practice questions aligned to the requested duration"
+    },
+    {
+      "step": 7,
+      "action": "Save run history",
+      "details": "Run logged to trace store with run_id run_study_001"
+    }
+  ],
+  "final_output": {
+    "study_plan": [
+      {
+        "segment": "Review key concepts",
+        "duration_minutes": 10,
+        "focus": ["supervised learning", "features and labels", "overfitting"]
+      },
+      {
+        "segment": "Active recall",
+        "duration_minutes": 10,
+        "focus": ["explain evaluation metrics", "compare training vs validation data"]
+      },
+      {
+        "segment": "Practice questions",
+        "duration_minutes": 10,
+        "focus": ["apply concepts to a simple dataset", "identify common mistakes"]
+      }
+    ],
+    "flashcards": [
+      {
+        "front": "What is the difference between a feature and a label?",
+        "back": "A feature is an input variable used for prediction; a label is the target value being predicted."
+      },
+      {
+        "front": "What does overfitting mean?",
+        "back": "Overfitting happens when a model learns training data too closely and performs poorly on new data."
+      },
+      {
+        "front": "Why do we use a validation set?",
+        "back": "A validation set helps estimate model performance during development without using the test set."
+      }
+    ],
+    "practice_questions": [
+      "Explain why a model with very high training accuracy might still perform poorly on test data.",
+      "Given a small dataset, how would you decide whether the model is overfitting?",
+      "Name two evaluation metrics you would use for a classification task and describe when each is useful."
+    ],
+    "session_summary": "Completed a 30-minute beginner study session on machine learning basics using class notes and quick reference material."
+  }
+}