Skip to content

Commit 341bc32

Browse files
CopilotYukaii
Copilot
and
Yukaii
committed
feat: add ai-conference-assistant web example with chat UI, jq tools, and progress tracking
Co-authored-by: Yukaii <4230968+Yukaii@users.noreply.github.com> Agent-Logs-Url: https://github.com/hackmdio/api-client/sessions/a73c91f7-229e-482d-b038-6bb8e454ab09
1 parent 8750936 commit 341bc32

27 files changed

Lines changed: 9011 additions & 0 deletions

‎examples/ai-conference-assistant/.gitignore‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.*
7+
.yarn/*
8+
!.yarn/patches
9+
!.yarn/plugins
10+
!.yarn/releases
11+
!.yarn/versions
12+
13+
# testing
14+
/coverage
15+
16+
# next.js
17+
/.next/
18+
/out/
19+
20+
# production
21+
/build
22+
23+
# misc
24+
.DS_Store
25+
*.pem
26+
27+
# debug
28+
npm-debug.log*
29+
yarn-debug.log*
30+
yarn-error.log*
31+
.pnpm-debug.log*
32+
33+
# env files (can opt-in for committing if needed)
34+
.env*
35+
36+
# vercel
37+
.vercel
38+
39+
# typescript
40+
*.tsbuildinfo
41+
next-env.d.ts

‎examples/ai-conference-assistant/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# HackMD Conference Assistant (AI-Powered)
2+
3+
A web-based AI assistant that helps you create book-mode collaborative note systems for conferences using the HackMD API. Built with Next.js, Vercel AI SDK, and the `@hackmd/api` client.
4+
5+
## Features
6+
7+
- **Chat Interface**: Conversational AI that guides you through conference note creation
8+
- **Session Data Analysis**: Upload your conference session JSON; the AI uses a jq-like tool to efficiently analyze the data shape without consuming excessive tokens
9+
- **Reference Note Fetching**: Point the AI to an existing HackMD note (e.g., last year's conference) and it will analyze the format
10+
- **Markdown Preview**: Preview the generated homepage and all session pages before creating
11+
- **Rate-Limit-Aware Creation**: Batch note creation with configurable delay and real-time progress tracking via SSE
12+
- **Frontend API Key Entry**: No server-side secrets needed — provide your HackMD and OpenAI API keys from the browser
13+
14+
## Architecture
15+
16+
```
17+
┌─────────────────────────────────────────────────┐
18+
│ Browser (React) │
19+
│ │
20+
│ ┌──────────────┐ ┌──────────┐ ┌───────────┐ │
21+
│ │ Setup Panel │ │ Chat UI │ │ Preview │ │
22+
│ │ (API keys) │ │ (useChat)│ │ (Markdown)│ │
23+
│ └──────┬───────┘ └────┬─────┘ └───────────┘ │
24+
│ │ │ │
25+
└─────────┼───────────────┼────────────────────────┘
26+
│ │
27+
▼ ▼
28+
┌──────────────────────────────────────────────────┐
29+
│ Next.js API Routes │
30+
│ │
31+
│ POST /api/chat POST /api/create-notes │
32+
│ ├─ AI SDK streamText ├─ SSE progress stream │
33+
│ ├─ hackmd_get_me ├─ createTeamNote loop │
34+
│ ├─ hackmd_get_note ├─ Rate limit delay │
35+
│ ├─ hackmd_get_team_notes└─ Homepage with links │
36+
│ ├─ jq_query │
37+
│ └─ generate_pages │
38+
└──────────────────────────────────────────────────┘
39+
```
40+
41+
## Quick Start
42+
43+
### Prerequisites
44+
45+
- Node.js 18+
46+
- A [HackMD API token](https://hackmd.io/settings/api)
47+
- An [OpenAI API key](https://platform.openai.com/api-keys)
48+
49+
### Setup
50+
51+
```bash
52+
# From the repository root
53+
cd examples/ai-conference-assistant
54+
55+
# Install dependencies
56+
npm install
57+
58+
# Start the development server
59+
npm run dev
60+
```
61+
62+
Open [http://localhost:3000](http://localhost:3000) in your browser.
63+
64+
### Usage
65+
66+
1. **Enter your credentials** — HackMD API key, OpenAI API key, and team path
67+
2. **Upload session data** — Click the 📁 button to upload your `sessions.json`
68+
3. **Chat with the AI** — Tell it about your conference, reference notes, customizations
69+
4. **Preview** — The AI generates pages; preview them in the right panel
70+
5. **Create Notes** — Click "Create Notes", configure the delay, and watch progress
71+
72+
### Sample Session Data
73+
74+
A sample `sessions.json` is included at `public/sample-sessions.json`. The expected format:
75+
76+
```json
77+
[
78+
{
79+
"id": "session-001",
80+
"title": "Opening Keynote",
81+
"speaker": [{ "speaker": { "public_name": "John Doe" } }],
82+
"session_type": "keynote",
83+
"started_at": "2025-03-15T09:00:00Z",
84+
"finished_at": "2025-03-15T09:30:00Z",
85+
"tags": ["keynote"],
86+
"classroom": { "tw_name": "主舞台", "en_name": "Main Stage" },
87+
"language": "en",
88+
"difficulty": "General"
89+
}
90+
]
91+
```
92+
93+
## AI Tools
94+
95+
The AI agent has access to these tools during conversation:
96+
97+
| Tool | Purpose |
98+
|------|---------|
99+
| `hackmd_get_me` | Verify credentials, discover teams |
100+
| `hackmd_get_note` | Read existing notes for reference |
101+
| `hackmd_get_team_notes` | List team workspace notes |
102+
| `jq_query` | Token-efficient session data analysis (length, keys, group_by, select, map, sort_by, unique, etc.) |
103+
| `generate_pages` | Generate homepage + all session pages for preview |
104+
105+
## Rate Limiting
106+
107+
When creating notes, the tool includes:
108+
- Configurable delay between API requests (default: 300ms, recommended: 200-500ms)
109+
- Automatic 10-second pause on 429 (rate limit) errors
110+
- Real-time progress streaming via Server-Sent Events
111+
- Per-note error tracking with continuation
112+
113+
## Tech Stack
114+
115+
- **Next.js 16** — React framework with App Router
116+
- **Vercel AI SDK** — Streaming AI chat with tool use
117+
- **Tailwind CSS** — Styling
118+
- **HackMD REST API** — Note creation (via fetch wrapper)

‎examples/ai-conference-assistant/eslint.config.mjs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { defineConfig, globalIgnores } from "eslint/config";
2+
import nextVitals from "eslint-config-next/core-web-vitals";
3+
import nextTs from "eslint-config-next/typescript";
4+
5+
const eslintConfig = defineConfig([
6+
...nextVitals,
7+
...nextTs,
8+
// Override default ignores of eslint-config-next.
9+
globalIgnores([
10+
// Default ignores of eslint-config-next:
11+
".next/**",
12+
"out/**",
13+
"build/**",
14+
"next-env.d.ts",
15+
]),
16+
]);
17+
18+
export default eslintConfig;

‎examples/ai-conference-assistant/next.config.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import type { NextConfig } from "next";
2+
3+
const nextConfig: NextConfig = {
4+
/* config options here */
5+
};
6+
7+
export default nextConfig;

0 commit comments

Comments
 (0)