Skip to content

Pavilion-devs/ADK-Agents

BranchesTags

Repository files navigation

Shegs - AI-Powered Workspace Assistant

Your intelligent assistant for managing emails, calendar events, and tasks with natural language.

Shegs is an AI-powered workspace backend built with ADK-TS (Agent Development Kit) that helps you stay organized by managing your Google Calendar, Gmail, and tasks through natural conversation.

Features

  • AI Chat Interface: Natural language conversation with your workspace data
  • Gmail Integration: Read, analyze, and manage your emails
  • Google Calendar: View and manage your calendar events
  • Task Management: Create, update, and track your tasks
  • Email Priority Detection: AI-powered email prioritization
  • Daily Summaries: Get intelligent summaries of your day
  • Database-backed: Persistent storage with Prisma + SQLite/PostgreSQL

Tech Stack

  • Runtime: Node.js + TypeScript
  • AI Framework: ADK-TS (Agent Development Kit)
  • LLM: OpenAI GPT-4o-mini
  • Database: SQLite (local) / PostgreSQL (production)
  • ORM: Prisma
  • API: Express.js REST API
  • Authentication: Google OAuth 2.0

Quick Start

Prerequisites

  • Node.js 18+ installed
  • Google Cloud Console project with Gmail & Calendar APIs enabled
  • OpenAI API key

Installation

# Clone the repository
git clone <your-repo-url>
cd shegs

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# Initialize database
npx prisma db push

# Start development server
npm run dev

The server will start on http://localhost:3002

Test the API

# Health check
curl http://localhost:3002/api/health

# Chat with the AI assistant
curl -X POST http://localhost:3002/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What tasks do I have today?"}'

Environment Variables

Create a .env file in the root directory:

# Server
PORT=3002
NODE_ENV=development

# OpenAI API (Required)
OPENAI_API_KEY=sk-proj-YOUR_KEY_HERE

# Google OAuth (Required for Gmail/Calendar)
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3002/api/auth/google/callback
GOOGLE_REFRESH_TOKEN=your_refresh_token

# Database (SQLite for local development)
DATABASE_URL="file:./prisma/dev.db"

See .env.example for a complete template.

API Documentation

Full API documentation is available in API_DOCUMENTATION.md

Key Endpoints

Endpoint Method Description
/api/health GET Health check
/api/agent/chat POST Chat with AI assistant
/api/tasks GET/POST Manage tasks
/api/calendar/events GET Get calendar events
/api/email/inbox GET Get inbox emails
/api/email/priority GET Get prioritized emails
/api/auth/google GET Start Google OAuth

Google OAuth Setup

1. Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project
  3. Enable Gmail API and Google Calendar API

2. Create OAuth 2.0 Credentials

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth 2.0 Client ID
  3. Application type: Web application
  4. Authorized redirect URI: http://localhost:3002/api/auth/google/callback
  5. Copy the Client ID and Client Secret to your .env file

3. Get Refresh Token

# Start the server
npm run dev

# Visit in your browser
http://localhost:3002/api/auth/google

# Authorize the app
# Your refresh token will be logged to the console
# Copy it to your .env file as GOOGLE_REFRESH_TOKEN

Development

Available Scripts

npm run dev        # Start development server with hot reload
npm run build      # Build TypeScript to dist/
npm start          # Run production build
npm run db:studio  # Open Prisma Studio (database GUI)
npm run db:push    # Push schema changes to database

Database Management

# View database in GUI
npx prisma studio

# Reset database (WARNING: deletes all data)
rm prisma/dev.db
npx prisma db push

# Generate Prisma Client after schema changes
npx prisma generate

Deployment to Railway

Shegs is ready for deployment to Railway with PostgreSQL. See RAILWAY_DEPLOYMENT.md for detailed instructions.

Quick Deploy Steps:

  1. Update Database Provider: Change provider = "sqlite" to provider = "postgresql" in prisma/schema.prisma
  2. Push to GitHub: Commit and push your code
  3. Create Railway Project: Connect your GitHub repo
  4. Add PostgreSQL: Add PostgreSQL database to your Railway project
  5. Set Environment Variables: Add all required env vars in Railway dashboard
  6. Deploy: Railway will automatically build and deploy

Important: Remember to switch back to provider = "sqlite" for local development after deploying.

Project Structure

shegs/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── adk/                  # ADK agent configuration
│   ├── agents/               # AI agent definitions
│   ├── api/                  # Express routes
│   ├── auth/                 # Google OAuth logic
│   ├── db/                   # Database client
│   ├── services/             # Business logic
│   │   ├── calendar.service.ts
│   │   ├── email.service.ts
│   │   ├── task.service.ts
│   │   └── chat.service.ts
│   ├── tools/                # ADK tools for AI agent
│   │   ├── calendar.tool.ts
│   │   ├── email.tool.ts
│   │   └── task.tool.ts
│   └── prompts/              # AI prompt templates
├── prisma/
│   ├── schema.prisma         # Database schema
│   └── dev.db                # SQLite database (local)
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── .env                      # Environment variables (not in git)

How It Works

AI Agent Architecture

Shegs uses ADK-TS to create an AI agent with access to your workspace data:

  1. User sends a message via /api/agent/chat
  2. AI Agent receives the message and decides which tools to use
  3. Tools execute (e.g., fetch emails, create tasks, check calendar)
  4. AI processes the results and responds in natural language
  5. Response sent back to the user

Available AI Tools

The agent has access to these tools:

  • get_tasks - Retrieve all tasks
  • create_task - Create a new task
  • update_task - Update task status
  • get_calendar_events - Get upcoming calendar events
  • get_inbox - Get recent emails
  • get_unread_emails - Get unread emails
  • search_emails - Search emails by query
  • get_priority_emails - Get AI-prioritized emails
  • send_email - Send an email
  • mark_email_read - Mark email as read
  • get_daily_summary - Get AI-generated daily summary

Example Conversations

User: "What do I have today?"
Agent: [Uses get_calendar_events and get_tasks]
       "You have 3 meetings today: Team standup at 10am,
        Client call at 2pm, and Code review at 4pm.
        You also have 5 pending tasks..."

User: "Show me important emails"
Agent: [Uses get_priority_emails]
       "Here are your 3 most important emails:
        1. [CEO] Q4 Planning - High priority
        2. [Client] Project Feedback - Medium priority
        3. [Team] Sprint Review - Medium priority"

User: "Create a task to review the proposal"
Agent: [Uses create_task]
       "I've created a task 'Review the proposal' with
        medium priority and set it as pending."

Testing

Manual Testing

Use the API documentation to test endpoints with curl or Postman.

Test Plan

See TESTING_PLAN.md for comprehensive testing scenarios.

Troubleshooting

"Prisma Client not found"

npx prisma generate

"Google OAuth not working"

  • Ensure redirect URI matches exactly in Google Console and .env
  • Check that Gmail API and Calendar API are enabled
  • Verify your refresh token is valid

"OpenAI API errors"

  • Check your API key is correct
  • Ensure you have sufficient credits
  • Verify the model name is correct (gpt-4o-mini)

"Database connection failed"

  • For SQLite: Check prisma/dev.db file exists
  • For PostgreSQL: Verify DATABASE_URL is correct
  • Run npx prisma db push to create tables

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

License

MIT License - feel free to use this project for your hackathon, portfolio, or production apps!

Acknowledgments

  • ADK-TS: Built with the Agent Development Kit by IQ AI
  • OpenAI: Powered by GPT-4o-mini
  • Google APIs: Gmail & Calendar integration
  • Prisma: Database ORM
  • Railway: Deployment platform

Support

Shegs - Making workspace management effortless with AI.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages