Skip to content

README.md

Latest commit

 

History

History
172 lines (123 loc) · 4.18 KB

README.md

File metadata and controls

172 lines (123 loc) · 4.18 KB
Raw

Wikinsert API

The Wikinsert API serves pre-computed sentence-level relevance scores to the browser extension in real time. Unlike a traditional full-featured REST backend, this interface is intentionally narrow: it only exposes functionality required for the user study. All data processing and scoring occurs offline.

Overview

The API is built with Ktor, a Kotlin framework for building asynchronous servers and clients. It connects to a MongoDB database that stores pre-computed article data, sentence tokenization, and relevance scores generated by the data processing pipeline.

Key Design Principles

  • Minimal Interface: Only exposes endpoints required for the browser extension
  • Pre-computed Data: All responses are derived from pre-computed data, eliminating real-time inference
  • Low Latency: Ensures responsive user experience in the browser extension
  • Model Agnostic: API design is independent of the underlying scoring framework

API Endpoints

The API offers two main endpoints that support the complete functionality of the Wikinsert browser extension:

1. Heat-map Retrieval

POST /heatmap

Retrieves sentence-level relevance scores for a source article and target entity.

Parameters

Parameter Description
src_rev_id Revision ID of the source article
src_title Title of the source article
target_title Title of the target entity
lang Language code (e.g., "en")

Response

Returns a list of sentences from the source article, each with:

  • Sentence ID
  • Start and end character offsets
  • Relevance score (pre-computed using the XLocEI model)
[
  {
    "id": 0,
    "startOffset": 0,
    "endOffset": 120,
    "score": 0.75
  },
  {
    "id": 1,
    "startOffset": 121,
    "endOffset": 245,
    "score": 0.32
  }
]

2. Target Search

GET /searchTargets

Searches for suitable target entities that match a query and are associated with a specific source article.

Parameters

Parameter Description
q Search query
source_title Title of the source article
lang Language code (default: "en")

Response

Returns a list of target entities that match the search query:

[
  {
    "title": "Example Entity",
    "lang": "en",
    "description": "This is an example entity",
    "thumbnail": {
      "source": "https://example.com/image.jpg",
      "width": 100,
      "height": 100
    }
  }
]

Deployment

Prerequisites

  • JDK 11 or higher
  • MongoDB instance with pre-processed data
  • Docker (optional, for containerized deployment)

Environment Variables

Variable Description Default
MONGODB_URI MongoDB connection string mongodb://odin.st.lab.au.dk:27017
MONGODB_DATABASE MongoDB database name wikinsert

Building and Running

Local Development

./gradlew run

Production Deployment

Build a fat JAR:

./gradlew buildFatJar

Run the JAR:

java -jar build/libs/wikinsert-backend-all.jar

Docker Deployment

Build the Docker image:

./gradlew buildImage

Run the Docker container:

docker run -p 8080:8080 -e MONGODB_URI=mongodb://your-mongodb-host:27017 -e MONGODB_DATABASE=wikinsert wikinsert-backend

Dependencies

  • Ktor: Web framework for building asynchronous servers
  • kotlinx.serialization: JSON serialization/deserialization
  • MongoDB Kotlin Driver: MongoDB client for Kotlin
  • Koin: Dependency injection framework
  • Netty: Asynchronous event-driven network application framework

API Usage Examples

Heat-map Retrieval

curl -X POST "http://localhost:8080/heatmap?src_rev_id=1264244422&src_title=Salmon&target_title=Bream&lang=en"

Target Search

curl "http://localhost:8080/searchTargets?q=fish&source_title=Salmon&lang=en"