IMPLEMENTATION.md

# TEXT2SPARQL'26 Implementation Notes

## Current Status

- [x] Create challenge workspace
- [x] Create challenge-compatible placeholder API
- [x] Support both `/` and `/text2sparql`
- [x] Add registration snippet
- [x] Create local challenge environment with official client
- [x] Create rootless Docker container scaffold
- [ ] Replace placeholder query generation with the real pipeline
- [ ] Add semantic error detector / reranker
- [ ] Add dataset-specific adaptation logic
- [ ] Deploy public endpoint
- [ ] Submit registration PR to `CHALLENGERS.yaml`

## API Contract

Expected request:

- `GET /?dataset=<dataset-id>&question=<nl-question>`
- `GET /text2sparql?dataset=<dataset-id>&question=<nl-question>`

Expected response body:

```json
{
  "dataset": "https://text2sparql.aksw.org/2026/dbpedia/",
  "question": "Who directed Inception?",
  "query": "SELECT DISTINCT ?result WHERE { ?result ?p ?o . } LIMIT 1"
}
```

## Notes

- The official 2026 material is inconsistent about path shape, so this service
  supports both `/` and `/text2sparql`.
- The official examples still mention some 2025 dataset IDs. This scaffold
  accepts both 2025 and 2026 IDs for easier self-testing.
- For registration, the final public URL should point to the exact GET endpoint
  we want the organizers to call.
- The container setup is intentionally conservative:
  - non-root user inside the container
  - read-only root filesystem
  - localhost-only port publishing on the host
  - model directory mounted read-only