120 lines
2.9 KiB
Markdown
120 lines
2.9 KiB
Markdown
# Cavepedia Web
|
|
|
|
Next.js frontend with integrated PydanticAI agent for Cavepedia.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
web/
|
|
├── src/ # Next.js application
|
|
├── agent/ # PydanticAI agent (Python)
|
|
│ ├── main.py # Agent definition
|
|
│ ├── server.py # FastAPI server with AG-UI
|
|
│ └── pyproject.toml
|
|
└── ...
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 24+
|
|
- Python 3.13
|
|
- npm
|
|
- Google AI API Key (for the PydanticAI agent)
|
|
|
|
## Development
|
|
|
|
### 1. Install dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
This also installs the agent's Python dependencies via the `install:agent` script.
|
|
|
|
### 2. Set up environment variables
|
|
|
|
```bash
|
|
# Agent environment
|
|
cp agent/.env.example agent/.env
|
|
# Edit agent/.env with your API keys
|
|
```
|
|
|
|
### 3. Start development servers
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
This starts both the Next.js UI and PydanticAI agent servers concurrently.
|
|
|
|
## Agent Deployment
|
|
|
|
The agent can be containerized for production deployment.
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `GOOGLE_API_KEY` | Yes | Google AI API key for Gemini |
|
|
|
|
### Running in production
|
|
|
|
```bash
|
|
cd agent
|
|
uv run uvicorn server:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
## Web Deployment
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| `LANGGRAPH_DEPLOYMENT_URL` | Yes | `http://localhost:8000` | URL to the agent |
|
|
| `AUTH0_SECRET` | Yes | - | Session encryption key (`openssl rand -hex 32`) |
|
|
| `AUTH0_DOMAIN` | Yes | - | Auth0 tenant domain |
|
|
| `AUTH0_CLIENT_ID` | Yes | - | Auth0 application client ID |
|
|
| `AUTH0_CLIENT_SECRET` | Yes | - | Auth0 application client secret |
|
|
| `APP_BASE_URL` | Yes | - | Public URL of the app |
|
|
|
|
### Docker Compose (Full Stack)
|
|
|
|
```yaml
|
|
services:
|
|
web:
|
|
image: git.seaturtle.pw/cavepedia/cavepediav2-web:latest
|
|
ports:
|
|
- "3000:3000"
|
|
environment:
|
|
LANGGRAPH_DEPLOYMENT_URL: http://agent:8000
|
|
AUTH0_SECRET: ${AUTH0_SECRET}
|
|
AUTH0_DOMAIN: ${AUTH0_DOMAIN}
|
|
AUTH0_CLIENT_ID: ${AUTH0_CLIENT_ID}
|
|
AUTH0_CLIENT_SECRET: ${AUTH0_CLIENT_SECRET}
|
|
APP_BASE_URL: ${APP_BASE_URL}
|
|
depends_on:
|
|
- agent
|
|
|
|
agent:
|
|
image: git.seaturtle.pw/cavepedia/cavepediav2-agent:latest
|
|
environment:
|
|
GOOGLE_API_KEY: ${GOOGLE_API_KEY}
|
|
```
|
|
|
|
## Available Scripts
|
|
|
|
- `dev` - Start both UI and agent servers
|
|
- `dev:ui` - Start only Next.js
|
|
- `dev:agent` - Start only PydanticAI agent
|
|
- `build` - Build Next.js for production
|
|
- `start` - Start production server
|
|
- `lint` - Run ESLint
|
|
- `install:agent` - Install agent Python dependencies
|
|
|
|
## References
|
|
|
|
- [PydanticAI Documentation](https://ai.pydantic.dev/)
|
|
- [CopilotKit Documentation](https://docs.copilotkit.ai)
|
|
- [Next.js Documentation](https://nextjs.org/docs)
|
|
- [Auth0 Next.js SDK Examples](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md)
|