Conversational Gujarati - prototype 01

Deployed live at: conversational-gujarati-prototype-01.alex-hortfrancis.workers.dev

Prototype for a language learning app that helps users learn to speak Gujarati.

The project uses OpenAI's Agents SDK & Realtime API, with React, Vite, Hono, and Cloudflare Workers.

This project is based on this previous repo: hortfrancis/openai-realtime-agent-deployment-spike-01

Installation

Clone the repo

git clone https://github.com/hortfrancis/conversational-gujarati-prototype-01.git

.. or, using the GitHub CLI:

gh repo clone hortfrancis/conversational-gujarati-prototype-01

Navigate to the project directory

cd conversational-gujarati-prototype-01

Install dependencies

npm install

Configuration

Get your OpenAI API key from OpenAI's platform.

Create a .dev.vars file in the root directory and add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key

Important

You need to set up billing on your OpenAI account, and add some credit, to use the Realtime API.

If you don't do this, the Realtime connection will fail to initialise.

Running the project locally

Start the development server:

npm run dev

Open your browser and navigate to http://localhost:5173 (or the URL provided in the terminal) to see the React frontend.

Deployment

You will need a Cloudflare account. If you don't have one, you can sign up at Cloudflare.

The project is set up to use Cloudflare Workers for deployment. The frontend in the client browser calls the backend Worker to fetch an ephemeral (temporary) API key from OpenAI.

Set up your Wrangler CLI

This caches your Cloudflare credentials on your local machine.

npx wrangler login

Build the React app

This creates a dist/ directory and bundles the React app for production here.

npm run build

Deploy to Cloudflare Workers

This runs wrangler deploy using npm.

npm run deploy

This should create a new Workers deployment, available at the default URL of https://conversational-gujarati-prototype-01.<username>.workers.dev.

The URL will be printed in the terminal after deployment.

Add your OpenAI API key

You will need to add your OpenAI API key to the deployed Cloudflare Worker. You can do this in the Cloudflare dashboard.

• Go to "Workers & Pages" (in the left sidebar)
• Find the deployed Workers instance in the list & click the name
• Go to the "Settings" tab of the Worker instance
  • Scroll down to the "Variables and Secrets" section
  • Click "Add"
  • In the "Variables and Secrets" panel:
    • "Type" = "Secret"
    • "Variable name" = OPENAI_API_KEY
    • "Value" = your API key
  • Click "Deploy"

This will redeploy your Workers instance with the OpenAI API key as a environment secret.

Cloudflare's own documentation also covers adding secrets to Workers.

Additional Resources

• OpenAI Voice Agents documentation
• OpenAI Realtime API documentation
• Cloudflare Workers documentation
• Vite documentation
• React documentation
• Hono documentation