Function Proposal

Description

Marginalia Search is an independent, open-source search engine that focuses on non-commercial content (read more about the design and philosophy here).

Use Cases

• doing research on your favorite niche topics
• exploring the smolweb
• encouraging and supporting diversity amongst search engines
• feeling indie

Proposed API Interface

Function name

marginalia_search

Input parameters

The most basic parameters can be inferred from the HTTP API: https://api.marginalia.nu/{api_key}/search/{query}?index={index}&count={count}

(Note that there is a public API key, "public", that can be used by default. And Viktor is liberal about granting API keys to those who ask.)

The query parameter, however, supports a handful of features (which are documented at the bottom of any search result page: https://marginalia-search.com/search?query=query+features) that might be nice to include as explicit parameters to enhance the tool's utility.

E.g., if the site:<domain> query fragment were made an explicit input and an agent were asked a question that it can associate with a single domain name (e.g., "how can i contribute to the gofannon AI project?"), it might conjure a marginalia_search invocation with a query parameter like "site:the-ai-alliance.github.io contribution guide" and generate a better result than a broader query.

Including these as kwargs to the function would be relatively simple. But I'll await feedback to elaborate.

Return value

From the official API doc page:

import requests

url = "https://api.marginalia.nu/{key}/search/{query}";

rsp = requests.get(url.format(key='public', query="linear b"));

if rsp.ok:
  data = rsp.json()
  print ("Query: ", data['query'])
  print ("License: ", data['license'])
  print ("")
  for result in data['results']:
      print (result['url'])
      print ("\t" + result['title'])
      print ("\t" + result['description'])
      print ("")
else:
    print ("Bad Status " + str(rsp.status_code))

Error conditions

Standard HTTP codes; unsure if there are others.

Dependencies

Whichever library is already used for HTTP requests will be fine.

Documentation

Will live at docs/marginalia_search/ with links to the official docs.

Contribution Checklist

• I have read the CONTRIBUTING.md guide
• I have checked that this function doesn't already exist in the repository
• I have followed the single responsibility principle
• [?] I have designed a simple and intuitive API interface (incomplete—happy to elaborate on the query features depending on feedback)
• [?] I have considered error handling and logging (mostly—i haven't yet encountered any non-HTTP errors)
• I have outlined clear use cases
• I have considered documentation requirements

Development Plan

• Estimated timeline: a week or two, generously (seems like copying the google_search tool should take a few hours)
• Required resources: maintainer feedback + approval
• Testing strategy: will copy the google_search tool
• Documentation plan: will copy the google_search tool and link to marginalia's docs