README.md

OpenPoke 🌴

test OpenPoke is a simplified, open-source take on Interaction Company’s Poke assistant—built to show how a multi-agent orchestration stack can feel genuinely useful. It keeps the handful of things Poke is great at (email triage, reminders, and persistent agents) while staying easy to spin up locally.

• Multi-agent FastAPI backend that mirrors Poke's interaction/execution split, powered by OpenAI-compatible APIs.
• Gmail tooling via Composio for drafting/replying/forwarding without leaving chat.
• Trigger scheduler and background watchers for reminders and "important email" alerts.
• Next.js web UI that proxies everything through the shared .env, so plugging in API keys is the only setup.

Requirements

• Python 3.10+
• Node.js 18+
• npm 9+

Quickstart

1. Clone and enter the repo.

   git clone https://github.com/shlokkhemani/OpenPoke
   cd OpenPoke
   

2. Create a shared env file. Copy the template and open it in your editor:

   cp .env.example .env
   

3. Get your API keys and add them to .env:

   API Configuration (Required)

   • Configure your OpenAI-compatible API endpoint and API key in .env
   • Set API_BASE_URL to your API endpoint (e.g., https://api.friendli.ai/dedicated/v1)
   • Set API_KEY to your API key
   • All agent models can be configured via environment variables

   Composio (Required for Gmail)

   • Sign in at composio.dev
   • Create an API key
   • Set up Gmail integration and get your auth config ID
   • Replace your_composio_api_key_here and your_gmail_auth_config_id_here in .env

🚀 Quick Start (Docker - Recommended)

If you have Docker and docker-compose installed, you can get started immediately:

# Deploy with one command (includes security setup)
./deploy.sh

# Or manually with environment variables
docker-compose --env-file .env up --build -d

This will start both the API server (port 8001) and web UI (port 3000).

Production Deployment

For production deployments:

# Use production environment file
docker-compose --env-file .env.production up --build -d

# Or use specific environment file
docker-compose --env-file .env.staging up --build -d

Docker Features

• Security: Non-root containers with proper user isolation
• Health Checks: Built-in monitoring for service availability
• Resource Limits: CPU and memory constraints for stable performance
• Logging: Structured JSON logging with rotation
• Networks: Isolated network for service communication
• Volumes: Persistent storage for logs and runtime data

🛠️ Manual Setup (Alternative)

4. (Required) Create and activate a Python 3.10+ virtualenv:

   # Ensure you're using Python 3.10+
   python3.10 -m venv .venv
   source .venv/bin/activate
   
   # Verify Python version (should show 3.10+)
   python --version
   

   On Windows (PowerShell):

   # Use Python 3.10+ (adjust path as needed)
   python3.10 -m venv .venv
   .\.venv\Scripts\Activate.ps1
   
   # Verify Python version
   python --version
   

5. Install backend dependencies:

   pip install -r server/requirements.txt
   

6. Install frontend dependencies:

   npm install --prefix web
   

7. Start the FastAPI server:

   python -m server.server --reload
   

8. Start the Next.js app (new terminal):

   npm run dev --prefix web
   

9. Connect Gmail for email workflows. With both services running, open http://localhost:3000, head to Settings → Gmail, and complete the Composio OAuth flow. This step is required for email drafting, replies, and the important-email monitor.

The web app proxies API calls to the Python server using the values in .env, so keeping both processes running is required for end-to-end flows.

Project Layout

• server/ – FastAPI application and agents
• web/ – Next.js app
• server/data/ – runtime data (ignored by git)

License

MIT — see LICENSE.