🤖 Personal Productivity & Task Execution Agent

This project is built in disciplined phases. Current progress:

Sections below marked Planned describe intended behaviour; Measured results appear only once the evaluation in Phase 7 has actually run. No invented numbers.

1. Project Title · 2. Problem Statement ·
2. Key Features · 4. Architecture Overview ·
3. Tool Catalogue · 6. Technology Stack ·
4. Installation · 8. Environment Variables ·
5. Run Locally · 10. Run Tests ·
6. Example Requests · 12. Evaluation Results ·
7. Screenshots · 14. Demo · 15. Deployment ·
8. Known Limitations · 17. Future Roadmap

Deep-dives: Chatbot vs Agent · Multi-Step Workflows · Approval Model · Execution Limits · Security · Project Structure

Personal Productivity & Task Execution Agent.

Knowledge workers lose hours turning messy inputs — meeting notes, scattered priorities, half-formed plans — into organized, trackable work. A large language model can talk about that work fluently, but talking is not doing: it can't reliably create the tasks, remember what you referred to two messages ago, or refuse to act until you approve a destructive change.

This project builds an agent that closes that gap. It interprets a request, decides whether tools are even needed, selects and validates the right ones, executes actions against persistent storage, stops for human approval on every write, recovers from failures, and returns a result you can verify — backed by a complete execution log.

The goal is not to make the agent appear intelligent. The goal is to make it dependable — controllable, testable, observable, and safe.

When not to use an agent: if the steps are fixed and known ahead of time (e.g. "every night at 2am, export yesterday's tasks to CSV"), a deterministic workflow is cheaper, faster, and more reliable. An agent earns its cost only when the path must be decided from an open-ended request.

• 🧩 12 typed tools — every tool has a Pydantic schema for both input and output; write tools carry an explicit approval flag.
• 🔀 3 multi-step workflows — meeting-notes→tasks, daily planning, weekly review.
• ✋ Human-in-the-loop approval on every write action (target: 100% compliance), implemented as a first-class LangGraph interrupt() — not a bolted-on flag.
• 💾 Persistent storage — tasks, notes, and logs in Supabase Postgres; semantic note search via pgvector.
• 🧠 Session memory — resolves referential follow-ups like "mark the second one complete."
• 🛑 Reliability rails — max steps, per-tool retries, tool timeout, duplicate-call and loop detection.
• 🔎 Full observability — 12-field execution log per run, with an in-app log viewer. No secrets or chain-of-thought are ever stored or displayed.
• 🔁 Provider-agnostic — runs on free OpenRouter models for development; switches to OpenAI gpt-4o-mini for the graded eval with a single env-var change.

flowchart TD
    U([👤 User]) --> UI["🖥️ Streamlit UI<br/>chat · status · approval panel · log viewer"]
    UI --> CTRL["🎛️ Agent Controller<br/>LangGraph StateGraph"]

    subgraph AGENT["Agent Core (LangGraph)"]
        CTRL --> STATE["🧠 Agent State + Session Memory<br/>messages · referenced tasks · tool outputs · prefs"]
        STATE --> DECIDE{"🤔 Tool needed?"}
        DECIDE -- no --> RESP
        DECIDE -- yes --> SELECT["🎯 Select + validate tool<br/>(Pydantic args)"]
        SELECT --> WRITE{"✍️ Write action?"}
        WRITE -- yes --> APPROVE["✋ interrupt() → Human Approval"]
        WRITE -- no --> EXEC
        APPROVE -- approved --> EXEC["⚙️ Execute Tool"]
        APPROVE -- rejected --> RESP["📤 Response Generation"]
        EXEC --> VALIDATE["✅ Validate result"]
        VALIDATE --> LOOP{"Done / max steps?"}
        LOOP -- keep going --> STATE
        LOOP -- done --> RESP
    end

    SELECT -.calls.-> LLM["🌐 LLM Provider<br/>OpenRouter / OpenAI"]
    EXEC --> REG["🧰 Tool Registry"]
    REG --> TT["📋 Task Tools"] & NT["🗒️ Note Tools"] & PT["📅 Planning Tools"]
    TT & NT & PT --> DB[("🗄️ Postgres + pgvector<br/>tasks · notes · logs")]
    AGENT --> LOG[("📜 Execution Logs<br/>12 fields / run")]
    RESP --> UI

A full written explanation of each component lives in docs/A3_architecture.md.

The system draws a hard line between read and write operations. Every write pauses the graph and surfaces an approval card showing: proposed action · tool name · input arguments · expected effect · Approve / Reject (Edit where practical). Rejection returns control to the user with nothing executed.

Actions that always require approval: creating multiple tasks · updating a task · completing a task · deleting any record · sending/simulating email · creating reminders · any irreversible action.

Documented limits and why they were chosen:

Full input/output schemas, error tables, and examples: docs/A4_tool_specification.md.

Core tools (8):

Bonus tools (4 of the optional set):

# 1. Clone
git clone https://github.com/Rana-Haseeb/productivity-agent-2026.git
cd productivity-agent-2026

# 2. Virtual environment
python -m venv .venv
source .venv/Scripts/activate      # Windows (Git Bash);  use .venv/bin/activate on macOS/Linux

# 3. Dependencies
pip install -r requirements.txt

# 4. Secrets
cp .env.example .env               # then fill in the values

Configured via a git-ignored .env (template in .env.example):

⚠️ Use the session pooler connection string. The direct db.<ref>.supabase.co host is IPv6-only and will not resolve on IPv4-only networks or on Streamlit Cloud.

streamlit run app/main.py

pytest -q

39 tests, LLM mocked (fast, deterministic, no API key needed). The one real-DB persistence test skips automatically if DATABASE_URL is unset.

Evaluation (A5) and experiments (A6) make live LLM calls:

python -m eval.run_eval                                          # 32-case eval (free model)
python -m eval.run_eval --provider openai --model gpt-4o-mini    # graded run (recommended)
python -m experiments.run_experiments                            # the 5 experiments

Evaluated against a 34-case dataset (docs/A5_evaluation.md) covering direct-response, single-tool, multi-tool, approval, and failure/edge requests. Measured on cohere/north-mini-code:free, all 34 of 34 cases:

A perfect score deserves scrutiny. One scoring flaw was found and fixed first: an empty expected_tools made issubset vacuously true, so failure cases expecting no tool would have passed regardless of behaviour. The rule now requires zero calls when zero are expected, and re-scoring left the result unchanged — the agent genuinely called nothing on all three. Caveats (single sample, one model, self-authored dataset) are stated in docs/A5_evaluation.md.

Full dataset: docs/A5_evaluation.md. Populate the table above with:

python -m eval.run_eval --provider openai --model gpt-4o-mini

Measured on openrouter:cohere/north-mini-code:free — full analysis in docs/A6_experiments.md:

Drop the five PNGs into screenshots/ with these exact names and they render here automatically. Capture guide: screenshots/README.md.

Not recorded. See Known Limitations.

Deploy-ready for Streamlit Community Cloud — step-by-step guide in DEPLOYMENT.md. (Live URL to be added after deploy.)

• Free-model rate cap: OpenRouter free tier is limited to ~50 requests/day; the graded eval run therefore uses OpenAI gpt-4o-mini for consistency.
• Build size: sentence-transformers pulls torch (~2 GB), which can stress Streamlit Cloud build limits; a fallback to API-based embeddings is noted if deployment fails.
• Supabase networking: direct DB connections are IPv6-only; the app uses the session pooler.
• Single-user scope: the current design targets one user; multi-tenancy is future work.
• Evaluation scope: all 34 cases pass, but with one sample per case at temperature 0, on a single model, against a dataset authored alongside the agent — it measures correctness, not run-to-run variance or adversarial robustness.
• Reminders are recorded, not delivered: create_reminder stores the reminder, but the app has no notification channel, so nothing is sent. Stated in the tool description so the agent never claims otherwise.
• No demo video: not recorded. The Week 3 brief lists a demo video under its submission requirements, so this is a known gap rather than an oversight.

• Multi-user support with row-level security and per-user tool permissions.
• Real integrations (calendar, email) behind the same approval gate.
• Postgres-backed LangGraph checkpointer for durable cross-session resumption.
• Richer evaluation: adversarial prompt-injection suite and automated regression runs.
• Production observability (tracing, cost/latency dashboards, alerting).

Full review (≥5 risks + controls) in docs/A7_security_review.md (full analysis in docs/A7_security_review.md). Baked-in from day one:

• Secrets live only in a git-ignored .env; nothing sensitive is hard-coded or logged.
• Approval boundary prevents the model from executing writes unilaterally.
• Input validation via Pydantic on every tool argument rejects malformed/hallucinated calls.
• Prompt-injection posture: tool results and user content are treated as data, never as new instructions; the system prompt is version-controlled.
• Log privacy: execution logs store operational metadata only — never API keys or model reasoning.

productivity-agent-2026/
├── app/
│   ├── main.py                 # Streamlit entry / UI
│   ├── config.py               # env-based config, execution limits, provider registry
│   ├── agent/                  # LangGraph state machine
│   │   ├── graph.py            #   the StateGraph (nodes + edges)
│   │   ├── nodes.py            #   node implementations
│   │   ├── prompts.py          #   version-controlled prompts
│   │   └── state.py            #   typed AgentState + session memory
│   ├── tools/                  # task_tools · note_tools · planning_tools
│   ├── database/               # models.py · repository.py · schema.sql
│   ├── services/               # llm_service.py (provider-agnostic) · embeddings.py
│   └── observability/          # run_logger.py (renamed from "logging" to avoid stdlib shadowing)
├── tests/                      # ≥10 pytest tests
├── docs/                       # A2–A8 deliverables
├── scripts/                    # probe_tool_calling.py (+ results)
├── screenshots/
├── .env.example
├── requirements.txt
└── README.md