Thoughts about API design

[lintool]

Just thoughts... @ronakice @sahel-sh reactions welcome.

Two methods: rerank and rerank_batch.

Method signature:

    def rerank(self, query: Query, candidates: Candidates, k: int = 10) -> Candidates:

Commentary:

• I prefer an actual Query object as opposed to just a str. This will allow us to attach additional fields to include metadata, etc.
• I prefer an actual Candidates object as opposed to just a list of json objects. Again, this will allow us to attach other metadata, such as execution traces, etc.
• Contract is that the returned Candidates is a fresh object. I.e., the method is non-destructive - does not mess with the input.

The, rerank_batch would be:

    def rerank_batch(self, query: List[Query], candidates: List[Candidates], k: int = 10) -> Candidates:

rerank can just route to rerank_batch with a list of one object.