GrantGuide

GrantGuide is a Slack-native AI agent that turns chat history into actionable program memory for nonprofits, searching workspace info, tracking deadlines, and automating tasks in real time.

Comment

About the Project: GrantGuide 🏆

GrantGuide was built for the Slack Agent for Good hackathon track to empower nonprofit, research, and education teams. It acts as an intelligent workspace assistant that automates knowledge retrieval, tracks grant application deadlines, and drafts action-item checklists directly within Slack.

💡 Inspiration

Nonprofit and educational organizations spend an average of (30\%) of their time searching for information, coordinating deadlines, and tracking down decisions scattered across Slack history and spreadsheets. We wanted to build a privacy-first assistant that could retrieve institutional knowledge instantly, translate queries on-the-fly for multi-lingual volunteers, transcribe voice notes in the field, and proactively keep the team aligned with automated digests—allowing them to focus on what matters most: creating impact.

🛠️ How We Built It

GrantGuide is built on Python, utilizing the Slack Bolt SDK and Socket Mode to establish secure real-time connections without public endpoints.

        ┌──────────────────────────────────────────┐
          │              Slack Workspace             │
          └────────┬────────────────────────┬────────┘
                   │                        ▲
     User Message  │                        │  Rich Blocks
     / Audio/Reaction│                        │  & Checklist Fallbacks
                   ▼                        │
          ┌─────────────────────────────────┴────────┐
          │            GrantGuide Server             │
          │  (Socket Mode Client + http health)      │
          └────────┬────────────────────────┬────────┘
                   │                        ▲
    Query Context   │                        │  Fast LLM Responses
                   ▼                        │
          ┌─────────────────────────────────┴────────┐
          │             Groq Cloud LPU               │
          │     (llama-3.3-70b & Whisper-large)      │
          └──────────────────────────────────────────┘

The system operates via an advanced Search → Summarize → Act pipeline:

  1. Search (Keyword Indexer): Searches Slack channel histories and simulated Google Sheets databases. We use token-matching to score relevance: $$ \text{Relevance Score} = \frac{\text{Matches}}{\text{Query Words}} \times 0.5 $$
  2. Summarize (Groq LPU): Integrates the high-speed Groq API (llama-3.3-70b-versatile) to compile search results, translate queries, and transcribe voice messages.
  3. Act (MCP & Block Kit): Dispatches checklist posts directly into channels, tracks deadlines in a local SQLite database, and generates interactive metrics dashboards on the Slack App Home tab.

🚧 Challenges We Faced

1. API Rate Limits & SDK Migration

  • The Problem: The initial implementation relied entirely on Google Gemini APIs, which frequently ran into strict rate limit quotas during consecutive search queries.
  • The Solution: We migrated the primary chat completions and translation pipelines to Groq's low-latency LPU infrastructure. We also decoupled the codebase from legacy Generative AI libraries to future-proof the application.

2. Slack Web Client Redirect Glitches

  • The Problem: Standard Slack Canvas links (slack.com/canvas/...) failed to redirect correctly when clicked from browser-based Slack web clients, resulting in a "There's been a glitch" error page.
  • The Solution: We implemented dynamic workspace ID lookup via the team_info API to construct browser-compatible web URLs: $$\text{URL} = \text{https://app.slack.com/client/}\{team\_id\}\text{/canvas/}\{canvas\_id\}$$ We also enhanced the system to post the full checklist directly in the channel as a fallback so that users on free tiers could access the checklist content instantly.

3. Cloud Hosting Health Checks on Socket Mode

  • The Problem: Free-tier cloud providers require web apps to bind to an HTTP port and reply to health checks, but Socket Mode operates entirely over outbound WebSockets and does not open a local port.
  • The Solution: We integrated a tiny, lightweight daemon HTTP server in app.py that listens on the dynamic $PORT environment variable and replies with 200 OK. This makes the application compatible with both Render and Railway container runtimes.

4. In-Memory Cache Loss during Cloud Redeployment

  • The Problem: The temporary in-memory thread context dictionary would clear whenever the container rebuilt or redeployed, breaking Post reminder and Create canvas button actions on older messages.
  • The Solution: We designed a persistent SQLite database table (thread_context) to store the search state, allowing buttons on all future cards to remain functional indefinitely across server updates.

🧠 What We Learned

  • Decoupled SDK architectures: How to seamlessly transition core components from Gemini to Groq while maintaining local keyword-matching fallbacks.
  • SQLite for Agent Memory & Context: Storing conversation history and button action states persistently to reference past answers and support actions across container restarts.
  • State-of-the-Art Block Kit UX: Designing multi-tab dashboards, interactive modals, and thumbs-up/down feedback loops to build premium user experiences in Slack.

🛠️ Built With

GrantGuide was built using the following modern tools and technologies:

💻 Languages & Frameworks

  • Python (v3.11/v3.13): Core programming language powering the agent orchestration pipelines.
  • Slack Bolt for Python: Main Slack SDK framework used to handle workspace event listeners, actions routing, and views dispatching.

🧠 APIs & AI/ML Models

  • Groq Cloud LPU API: Powering chat completions and multi-lingual query translation using the ultra-fast llama-3.3-70b-versatile model.
  • Groq Whisper API (whisper-large-v3): High-accuracy speech-to-text model for transcribing mobile voice queries.
  • Google Gemini API: Utilized gemini-embedding-2 to inspect and test semantic token embeddings.

💾 Databases & State Persistence

  • SQLite3: Lightweight relational database engine used for caching past conversation summaries, storing persistent thread search context (thread_context), logging error analytics, recording user rating feedback (👍/👎), and storing tracked deadlines.

☁️ Infrastructure & Platforms

  • Railway: Primary cloud host used to run the Docker container 24/7.
  • Docker: Containerization engine used to package Python environments, dependencies, and code for platform-independent cloud execution.
  • GitHub: Version control host for the codebase repository and automated Railway CD triggers.
  • APScheduler: Advanced Python Scheduler used for dispatching daily digests, weekly recaps, and cleaning up archived databases.

Built With

Share this project:

Updates