Skip to content

Commit 2b762bc

Browse files
tuananhit1612tuananhit1612
committed
docs: update docs site content and links
1 parent 8095120 commit 2b762bc

File tree

10 files changed

+770
-624
lines changed

10 files changed

+770
-624
lines changed

‎docs/documentation/.source/index.ts‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
// @ts-nocheck -- skip type checking
2-
import * as docs_14 from "../content/sponsor.mdx?collection=docs&hash=1765003858000"
3-
import * as docs_13 from "../content/license.mdx?collection=docs&hash=1765003858000"
4-
import * as docs_12 from "../content/introduction.mdx?collection=docs&hash=1765003858000"
5-
import * as docs_11 from "../content/index.mdx?collection=docs&hash=1765003858000"
6-
import * as docs_10 from "../content/getting-started.mdx?collection=docs&hash=1765003858000"
7-
import * as docs_9 from "../content/faqs.mdx?collection=docs&hash=1765003858000"
8-
import * as docs_8 from "../content/error-handling.mdx?collection=docs&hash=1765003858000"
9-
import * as docs_7 from "../content/ecosystem.mdx?collection=docs&hash=1765003858000"
10-
import * as docs_6 from "../content/data-models.mdx?collection=docs&hash=1765003858000"
11-
import * as docs_5 from "../content/configuration.mdx?collection=docs&hash=1765003858000"
12-
import * as docs_4 from "../content/community-support.mdx?collection=docs&hash=1765003858000"
13-
import * as docs_3 from "../content/basic-usage.mdx?collection=docs&hash=1765003858000"
14-
import * as docs_2 from "../content/authentication.mdx?collection=docs&hash=1765003858000"
15-
import * as docs_1 from "../content/api.mdx?collection=docs&hash=1765003858000"
16-
import * as docs_0 from "../content/ai-services.mdx?collection=docs&hash=1765003858000"
2+
import * as docs_14 from "../content/sponsor.mdx?collection=docs&hash=1765185956937"
3+
import * as docs_13 from "../content/license.mdx?collection=docs&hash=1765185956937"
4+
import * as docs_12 from "../content/introduction.mdx?collection=docs&hash=1765185956937"
5+
import * as docs_11 from "../content/index.mdx?collection=docs&hash=1765185956937"
6+
import * as docs_10 from "../content/getting-started.mdx?collection=docs&hash=1765185956937"
7+
import * as docs_9 from "../content/faqs.mdx?collection=docs&hash=1765185956937"
8+
import * as docs_8 from "../content/error-handling.mdx?collection=docs&hash=1765185956937"
9+
import * as docs_7 from "../content/ecosystem.mdx?collection=docs&hash=1765185956937"
10+
import * as docs_6 from "../content/data-models.mdx?collection=docs&hash=1765185956937"
11+
import * as docs_5 from "../content/configuration.mdx?collection=docs&hash=1765185956937"
12+
import * as docs_4 from "../content/community-support.mdx?collection=docs&hash=1765185956937"
13+
import * as docs_3 from "../content/basic-usage.mdx?collection=docs&hash=1765185956937"
14+
import * as docs_2 from "../content/authentication.mdx?collection=docs&hash=1765185956937"
15+
import * as docs_1 from "../content/api.mdx?collection=docs&hash=1765185956937"
16+
import * as docs_0 from "../content/ai-services.mdx?collection=docs&hash=1765185956937"
1717
import { _runtime } from "fumadocs-mdx"
1818
import * as _source from "../source.config"
19-
export const docs = _runtime.doc<typeof _source.docs>([{ info: {"path":"ai-services.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/ai-services.mdx"}, data: docs_0 }, { info: {"path":"api.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/api.mdx"}, data: docs_1 }, { info: {"path":"authentication.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/authentication.mdx"}, data: docs_2 }, { info: {"path":"basic-usage.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/basic-usage.mdx"}, data: docs_3 }, { info: {"path":"community-support.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/community-support.mdx"}, data: docs_4 }, { info: {"path":"configuration.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/configuration.mdx"}, data: docs_5 }, { info: {"path":"data-models.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/data-models.mdx"}, data: docs_6 }, { info: {"path":"ecosystem.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/ecosystem.mdx"}, data: docs_7 }, { info: {"path":"error-handling.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/error-handling.mdx"}, data: docs_8 }, { info: {"path":"faqs.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/faqs.mdx"}, data: docs_9 }, { info: {"path":"getting-started.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/getting-started.mdx"}, data: docs_10 }, { info: {"path":"index.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/index.mdx"}, data: docs_11 }, { info: {"path":"introduction.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/introduction.mdx"}, data: docs_12 }, { info: {"path":"license.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/license.mdx"}, data: docs_13 }, { info: {"path":"sponsor.mdx","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/sponsor.mdx"}, data: docs_14 }]);
20-
export const meta = _runtime.meta<typeof _source.meta>([{ info: {"path":"meta.json","absolutePath":"D:/Dev/UrbanReflex/docs/documentation/content/meta.json"}, data: {"title":"Documentation","pages":["index","introduction","---Getting Started---","getting-started","basic-usage","---Reference---","api","data-models","ai-services","authentication","error-handling","---Resources---","ecosystem","configuration","---","faqs","sponsor","community-support","license"]} }]);
19+
export const docs = _runtime.doc<typeof _source.docs>([{ info: {"path":"ai-services.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/ai-services.mdx"}, data: docs_0 }, { info: {"path":"api.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/api.mdx"}, data: docs_1 }, { info: {"path":"authentication.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/authentication.mdx"}, data: docs_2 }, { info: {"path":"basic-usage.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/basic-usage.mdx"}, data: docs_3 }, { info: {"path":"community-support.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/community-support.mdx"}, data: docs_4 }, { info: {"path":"configuration.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/configuration.mdx"}, data: docs_5 }, { info: {"path":"data-models.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/data-models.mdx"}, data: docs_6 }, { info: {"path":"ecosystem.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/ecosystem.mdx"}, data: docs_7 }, { info: {"path":"error-handling.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/error-handling.mdx"}, data: docs_8 }, { info: {"path":"faqs.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/faqs.mdx"}, data: docs_9 }, { info: {"path":"getting-started.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/getting-started.mdx"}, data: docs_10 }, { info: {"path":"index.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/index.mdx"}, data: docs_11 }, { info: {"path":"introduction.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/introduction.mdx"}, data: docs_12 }, { info: {"path":"license.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/license.mdx"}, data: docs_13 }, { info: {"path":"sponsor.mdx","absolutePath":"D:/UrbanReflex/docs/documentation/content/sponsor.mdx"}, data: docs_14 }]);
20+
export const meta = _runtime.meta<typeof _source.meta>([{ info: {"path":"meta.json","absolutePath":"D:/UrbanReflex/docs/documentation/content/meta.json"}, data: {"title":"Documentation","pages":["index","introduction","---Getting Started---","getting-started","basic-usage","---Reference---","api","data-models","ai-services","authentication","error-handling","---Resources---","ecosystem","configuration","---","faqs","sponsor","community-support","license"]} }]);

‎docs/documentation/content/ai-services.mdx‎

Lines changed: 89 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,129 @@
11
---
22
title: AI Services
3-
description: Chatbot, classification, and RAG
3+
description: Gemini-powered chatbot (SSE), classification, and optional vector search
44
---
55

66
# AI Services
77

8-
## RAG Chatbot
8+
UrbanReflex AI stack uses Gemini for generation and supports optional vector search (Pinecone) for RAG. Chatbot endpoints support streaming (SSE) and non-streaming. Classification is exposed via citizen-report API.
99

10-
Sử dụng Gemini AI + Pinecone vector database.
10+
---
11+
12+
## Chatbot (Gemini)
13+
14+
**Endpoint:** `POST /ai-service/chatbot/chat`
1115

12-
### POST /ai-service/chatbot/chat
16+
- Streaming SSE (default): emits `start`, `token`, `end` events.
17+
- Non-streaming: add `?stream=false`.
18+
- Optional: `conversation_id`, `user_id` to maintain context.
1319

20+
**Request (non-streaming example)**
1421
```json
1522
{
16-
"message": "Chất lượng không khí Quận 1?",
17-
"session_id": "session_123"
23+
"message": "What is the air quality in District 1?",
24+
"conversation_id": "conv_123456",
25+
"user_id": "[email protected]"
1826
}
1927
```
2028

21-
**Response:**
22-
29+
**Response (non-streaming)**
2330
```json
2431
{
25-
"response": "Quận 1 có PM2.5 là 25.5 µg/m³...",
26-
"sources": [{"type": "aqi_station", "id": 12345}],
27-
"suggestions": ["Xem dự báo", "Đặt cảnh báo"]
32+
"conversation_id": "conv_123456",
33+
"response": "The current air quality in District 1 is moderate with PM2.5 at 35 µg/m³...",
34+
"sources": [
35+
{
36+
"type": "AirQualityObserved",
37+
"id": "urn:ngsi-ld:AirQualityObserved:District1-001",
38+
"timestamp": "2025-12-08T10:00:00Z"
39+
}
40+
],
41+
"timestamp": "2025-12-08T10:30:45Z"
2842
}
2943
```
3044

31-
## Report Classification
45+
**Response (streaming SSE snippet)**
46+
```
47+
data: {"type": "start", "conversation_id": "conv_123456"}
48+
data: {"type": "token", "content": "The"}
49+
data: {"type": "token", "content": " current"}
50+
data: {"type": "end", "full_response": "The current air quality in District 1 is..."}
51+
```
3252

33-
### POST /citizen-reports/classify
53+
### Chat History
54+
- `GET /ai-service/chatbot/history/{conversation_id}`
55+
- `DELETE /ai-service/chatbot/history/{conversation_id}` (204)
3456

35-
```json
36-
{
37-
"title": "Đèn đường không sáng",
38-
"description": "Đèn ở góc đường đã tắt 3 ngày"
39-
}
40-
```
57+
---
4158

42-
**Response:**
59+
## Report Classification (NLP + POI priority)
4360

61+
**Endpoint:** `POST /api/v1/citizen-reports/classify/{entity_id}`
62+
63+
**Response (example)**
4464
```json
4565
{
46-
"category": "streetlight",
47-
"confidence": 0.95,
48-
"priority_suggestion": "medium"
66+
"entity_id": "urn:ngsi-ld:CitizenReport:001",
67+
"category": "infrastructure",
68+
"priority": "high",
69+
"confidence": 0.89,
70+
"poi_proximity": {
71+
"nearby_pois": [
72+
{ "type": "hospital", "distance": 250, "name": "District 1 Hospital" }
73+
],
74+
"priority_boost": 1
75+
},
76+
"updated_at": "2025-12-08T10:30:00Z"
4977
}
5078
```
5179

52-
## Vector Search
80+
Errors:
81+
- 404 if report not found in Orion-LD
82+
- 500 if NLP service unavailable
83+
84+
---
5385

54-
### POST /ai/search
86+
## Vector Search (optional RAG)
5587

88+
**Endpoint:** `POST /ai/search` (if enabled)
5689
```json
5790
{
58-
"query": "Tìm báo cáo đèn đường hỏng Quận 1",
91+
"query": "Find broken streetlight reports in District 1 this month",
5992
"limit": 10
6093
}
6194
```
95+
**Response (example)**
96+
```json
97+
{
98+
"results": [
99+
{
100+
"type": "citizen_report",
101+
"relevance_score": 0.95,
102+
"data": {
103+
"id": "urn:ngsi-ld:CitizenReport:001",
104+
"title": "Broken streetlight on Main Street",
105+
"category": "streetlight",
106+
"status": "open"
107+
}
108+
}
109+
],
110+
"total_results": 12
111+
}
112+
```
113+
114+
---
62115

63116
## Configuration
64117

118+
`.env` (backend):
65119
```bash
66-
# Required
67-
GEMINI_API_KEY="your-key"
68-
PINECONE_API_KEY="your-key"
69-
PINECONE_INDEX_NAME="urbanreflex-index"
120+
# AI
121+
GEMINI_API_KEY=your_key_here
122+
123+
# Vector search (optional)
124+
PINECONE_API_KEY=your_key_here
125+
PINECONE_ENVIRONMENT=your_env
126+
PINECONE_INDEX_NAME=urbanreflex-index
70127
```
128+
129+
If Pinecone keys are absent, chatbot still works without RAG. Set API keys and restart backend to enable vector search. See full API details in [`docs/API_REFERENCE.md`](https://github.com/minhe51805/UrbanReflex/blob/main/docs/API_REFERENCE.md).

‎docs/documentation/content/api.mdx‎

Lines changed: 95 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,127 @@
11
---
22
title: API Reference
3-
description: Complete REST API documentation
3+
description: REST API overview and key endpoints
44
---
55

66
# API Reference
77

8-
**Base URL:** `http://localhost:8000/v1`
8+
High-level overview of the REST API. For full details, examples, and error formats, see the complete reference at [`docs/API_REFERENCE.md`](https://github.com/minhe51805/UrbanReflex/blob/main/docs/API_REFERENCE.md).
99

10-
## Air Quality
10+
---
1111

12-
### GET /aqi/stations
12+
## Base URLs
1313

14-
```bash
15-
curl "/aqi/stations?limit=10&country=VN"
16-
```
14+
- Dev: `http://localhost:8000`
15+
- Docs: `/docs` (Swagger), `/redoc` (ReDoc), schema `/openapi.json`
16+
- Namespace: `/api/v1/` (all endpoints below assume this prefix)
1717

18-
| Parameter | Type | Description |
19-
|-----------|------|-------------|
20-
| `limit` | int | Max results (default: 100) |
21-
| `country` | string | Country code (ISO) |
22-
| `city` | string | City name |
18+
---
2319

24-
### GET /aqi/stations/:id
20+
## Auth Status
21+
22+
- Current dev mode: most endpoints do **not** require auth.
23+
- Planned: JWT Bearer (`/auth/login`) and API Key (`X-API-Key`).
24+
25+
---
26+
27+
## Common Parameters
28+
29+
- Pagination: `limit` (default 100, max 1000), `offset` (default 0), `page` (alternative to offset).
30+
- Filtering (typical): `category`, `priority`, `status`, `type`, `created_after`, `created_before`.
31+
- Sorting: `sort_by`, `order` (`asc`/`desc`, default `desc`).
32+
33+
---
34+
35+
## Error Format (consistent)
2536

2637
```json
2738
{
28-
"id": 12345,
29-
"name": "District 1",
30-
"measurements": [
31-
{"parameter": "pm25", "value": 25.5}
32-
]
39+
"detail": "Error message describing what went wrong",
40+
"status_code": 400,
41+
"error_type": "ValidationError"
3342
}
3443
```
3544

36-
## NGSI-LD
45+
Common statuses: 200/201/204, 400/401/403/404/422, 500/502/503.
3746

38-
### GET /ngsi-ld/entities
47+
---
3948

40-
```bash
41-
curl "/ngsi-ld/entities?type=RoadSegment&limit=50"
42-
```
49+
## Citizen Reports
50+
51+
- **Classify**: `POST /api/v1/citizen-reports/classify/{entity_id}` — NLP + POI priority.
52+
- **Get**: `GET /api/v1/citizen-reports/{entity_id}` — NGSI-LD entity payload.
53+
- **List**: `GET /api/v1/citizen-reports` — filters: `category`, `priority`, `status`; pagination.
54+
- **Create**: `POST /api/v1/citizen-reports` — description, location (GeoJSON Point), category, reportedBy, images.
55+
- **Update**: `PATCH /api/v1/citizen-reports/{entity_id}` — status, assignedTo, notes.
56+
- **Delete**: `DELETE /api/v1/citizen-reports/{entity_id}` — 204.
57+
58+
---
59+
60+
## AI Chatbot
61+
62+
- **Chat (streaming SSE)**: `POST /ai-service/chatbot/chat`
63+
- Body: `message` (required), optional `conversation_id`, `user_id`.
64+
- Streaming tokens (`start`, `token`, `end`). Non-stream: `?stream=false`.
65+
- **History**: `GET /ai-service/chatbot/history/{conversation_id}`
66+
- **Delete history**: `DELETE /ai-service/chatbot/history/{conversation_id}`
67+
68+
---
69+
70+
## Items (placeholder CRUD)
71+
72+
- **List**: `GET /api/v1/items?skip=0&limit=100`
73+
- **Get**: `GET /api/v1/items/{item_id}`
74+
- **Create**: `POST /api/v1/items` (name, description, price, tax)
75+
76+
---
4377

4478
## Users
4579

46-
### GET /users/me
80+
- **Current user**: `GET /api/v1/users/me` (Bearer planned)
81+
- **List users (admin)**: `GET /api/v1/users?limit=&offset=&role=`
4782

48-
```bash
49-
curl -H "Authorization: Bearer TOKEN" "/users/me"
50-
```
83+
---
5184

52-
### POST /users/api-keys
85+
## Admin
5386

54-
```json
55-
{"name": "My Key", "description": "For app"}
56-
```
87+
- **Health**: `GET /admin/health` — status of backend, Orion-LD, AI service; uptime; version.
88+
- **Stats**: `GET /admin/stats` — reports by category/priority, totals, active users.
5789

58-
## Citizen Reports
90+
---
5991

60-
### POST /citizen-reports
92+
## NGSI-LD Integration
6193

62-
```bash
63-
curl -X POST "/citizen-reports" \
64-
-H "Authorization: Bearer TOKEN" \
65-
-F "title=Broken light" \
66-
-F "category=streetlight"
67-
```
94+
Directly via Orion-LD (dev):
95+
96+
- Base: `http://localhost:1026/ngsi-ld/v1`
97+
- List entities: `GET /entities`
98+
- Get by ID: `GET /entities/{entity_id}`
99+
- Query by type: `GET /entities?type=CitizenReport`
100+
- Geo query: `GET /entities?type=CitizenReport&georel=near;maxDistance==1000&geometry=Point&coordinates=[lon,lat]`
101+
- Temporal: `GET /temporal/entities?type=AirQualityObserved&timerel=after&timeAt=2025-12-01T00:00:00Z`
68102

69-
## AI Services
103+
---
70104

71-
### POST /ai/chat
105+
## Rate Limiting & Versioning (planned)
72106

73-
```json
74-
{
75-
"message": "Air quality today?",
76-
"context": {"location": {"lat": 10.77, "lon": 106.69}}
77-
}
107+
- Planned limits: anonymous 100/h, authenticated 1000/h, admin 10000/h (`X-RateLimit-*` headers).
108+
- Versioning: current `/api/v1/`; future breaking changes will use `/api/v2/`. Deprecation headers/messages may be returned.
109+
110+
---
111+
112+
## Testing (quick)
113+
114+
```bash
115+
# Health
116+
curl http://localhost:8000/health
117+
118+
# Classify a citizen report
119+
curl -X POST http://localhost:8000/api/v1/citizen-reports/classify/urn:ngsi-ld:CitizenReport:001
120+
121+
# Chat (non-streaming)
122+
curl -X POST "http://localhost:8000/ai-service/chatbot/chat?stream=false" \
123+
-H "Content-Type: application/json" \
124+
-d '{"message": "What is the air quality in District 1?"}'
78125
```
126+
127+
For complete examples and responses, read [`docs/API_REFERENCE.md`](https://github.com/minhe51805/UrbanReflex/blob/main/docs/API_REFERENCE.md).

0 commit comments

Comments
 (0)