# HHAI Project Rules
**Open Urban Data Commons — Development Guidelines**
Version 2.0 · hhai.city · 2026

---

## PROJECT CONTEXT

HHAI = Open Urban Data Commons
- A curated research platform for urban intelligence
- 29 public resources across 4 categories
- 6 live HK government APIs
- AI agents powered by DeepSeek

---

## RESOURCE CATEGORIES

| Category | IDs | Description |
|----------|-----|-------------|
| APIs | C01–C06 | Live HK government endpoints |
| Documents | A01, A02, B17, S01 | PDF reports and policy docs |
| Code & Repos | A03–A05, B01–B16 | GitHub repos, notebooks, tools |
| Guides | B13, B16, C05, C06, S02, S03 | Articles and web resources |

---

## CODING STANDARDS

### API Integration
- Always use resource IDs (C01, A02, etc.)
- Generate working code immediately
- Use `requests` (Python) or `fetch` (JS)
- Include error handling

### RAG Implementation
- Chunk PDFs at 1000 tokens with 200 overlap
- Use RecursiveCharacterTextSplitter
- Cite resource IDs in responses

### Data Sources
- Prefer beginner resources unless specified
- Link to related resources via "Alternates" field
- Always provide access method (API/download)

---

## FILE STRUCTURE

```
public/static/
── HHAI_RAG_SKILL.md      # Full catalog skill
├── hhai.cursorrules       # This file
├── skills/
│   ├── api-skill.md       # API-focused skill
│   ├── document-skill.md  # Document analysis skill
│   ├── code-skill.md      # Code repos skill
│   ── dataset-skill.md   # Dataset analysis skill
└── rag-docs/              # Individual resource markdown files
    ├── a01-*.md
    ├── b01-*.md
    └── c01-*.md
```

---

## AI BACKEND

- **Provider:** DeepSeek
- **Model:** deepseek-chat
- **API Key:** Via environment variable `DEEPSEEK_API_KEY`
- **Endpoint:** https://api.deepseek.com/v1/chat/completions

---

## QUICK REFERENCE

### API Endpoints
- C01: https://www.bd.gov.hk/en/resources/open-data/building-info-api
- C02: https://api.data.gov.hk/v1/historical-archive/get-file?url=https://openapi.data.gov.hk/dataset/land-search
- C03: https://api.data.gov.hk/v1/historical-archive/get-file?url=https://openapi.data.gov.hk/dataset/parking-vacancy
- C04: https://api.data.gov.hk/v1/historical-archive/get-file?url=https://openapi.data.gov.hk/dataset/aqhi
- C05: https://api.data.gov.hk/en/data/api-spec
- C06: https://data.gov.hk/

### GitHub Repos
- A03: https://github.com/urban-llm/awesome-urban-llm-agents
- A04: https://github.com/urban-model-platform/ump
- A05: https://github.com/city-digital-twin/cdt-framework
- B01: https://github.com/autodesk-platform-services/aps
- B06: https://github.com/geolab-hk/geolab
- B07: https://github.com/mcp-open-data-hk/mcp

---

*Part of HHAI Open Urban Data Commons · hhai.city*