KosmoKrator

data

Open Library Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Open Library KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.open_library.*. Use lua_read_doc("integrations.open-library") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Open Library workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.open_library.search_books({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("open-library"))' --json
kosmo integrations:lua --eval 'print(docs.read("open-library.search_books"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local open_library = app.integrations.open_library
local result = open_library.search_books({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.open_library, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.open_library.default.* or app.integrations.open_library.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Open Library, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Open Library

Namespace: open-library

Use this integration to retrieve public Open Library book metadata: search results, works, editions, ISBN records, author records, author works, subject works, recent changes, legacy Books API bibkey lookups, and cover image URLs.

Authentication

The public read APIs used here require no credentials.

Tools

  • open_library_search_books: search books and works.
  • open_library_search_authors: search authors.
  • open_library_work: retrieve one work by work ID.
  • open_library_work_editions: list editions for a work.
  • open_library_work_ratings: retrieve work ratings.
  • open_library_work_bookshelves: retrieve bookshelf counts for a work.
  • open_library_edition: retrieve one edition by edition ID.
  • open_library_isbn: retrieve an edition by ISBN.
  • open_library_books: legacy bibkey lookup for ISBN, LCCN, OCLC, and OLID.
  • open_library_author: retrieve one author.
  • open_library_author_works: list works by an author.
  • open_library_subject: list works for a subject.
  • open_library_recent_changes: list recent changes.
  • open_library_cover_url: build an Open Library cover image URL.

Return Notes

Open Library responses keep upstream field names. Search results use docs, numFound or num_found, and pagination fields. Work, edition, author, and subject endpoints return Open Library JSON records directly.

For cover images, Open Library exposes deterministic image URLs. The cover tool does not fetch the image; it returns the URL to use.

Examples

local books = tools.open_library_search_books({
  q = "the lord of the rings",
  fields = "key,title,author_name,first_publish_year,cover_i",
  limit = 5
})

local work = tools.open_library_work({
  id = "OL27448W"
})

local cover = tools.open_library_cover_url({
  type = "isbn",
  value = "9780140328721",
  size = "L"
})
Raw agent markdown 
# Open Library

Namespace: `open-library`

Use this integration to retrieve public Open Library book metadata: search
results, works, editions, ISBN records, author records, author works, subject
works, recent changes, legacy Books API bibkey lookups, and cover image URLs.

## Authentication

The public read APIs used here require no credentials.

## Tools

- `open_library_search_books`: search books and works.
- `open_library_search_authors`: search authors.
- `open_library_work`: retrieve one work by work ID.
- `open_library_work_editions`: list editions for a work.
- `open_library_work_ratings`: retrieve work ratings.
- `open_library_work_bookshelves`: retrieve bookshelf counts for a work.
- `open_library_edition`: retrieve one edition by edition ID.
- `open_library_isbn`: retrieve an edition by ISBN.
- `open_library_books`: legacy bibkey lookup for ISBN, LCCN, OCLC, and OLID.
- `open_library_author`: retrieve one author.
- `open_library_author_works`: list works by an author.
- `open_library_subject`: list works for a subject.
- `open_library_recent_changes`: list recent changes.
- `open_library_cover_url`: build an Open Library cover image URL.

## Return Notes

Open Library responses keep upstream field names. Search results use `docs`,
`numFound` or `num_found`, and pagination fields. Work, edition, author, and
subject endpoints return Open Library JSON records directly.

For cover images, Open Library exposes deterministic image URLs. The cover tool
does not fetch the image; it returns the URL to use.

## Examples

```lua
local books = tools.open_library_search_books({
  q = "the lord of the rings",
  fields = "key,title,author_name,first_publish_year,cover_i",
  limit = 5
})

local work = tools.open_library_work({
  id = "OL27448W"
})

local cover = tools.open_library_cover_url({
  type = "isbn",
  value = "9780140328721",
  size = "L"
})
```
Metadata-derived Lua example 
local result = app.integrations.open_library.search_books({})
print(result)

Functions

search_books Read

Search books and works.

Lua path
app.integrations.open_library.search_books
Full name
open-library.open_library_search_books
ParameterTypeRequiredDescription
No parameters.
search_authors Read

Search authors.

Lua path
app.integrations.open_library.search_authors
Full name
open-library.open_library_search_authors
ParameterTypeRequiredDescription
No parameters.
work Read

Get one work by ID.

Lua path
app.integrations.open_library.work
Full name
open-library.open_library_work
ParameterTypeRequiredDescription
No parameters.
work_editions Read

List editions for a work.

Lua path
app.integrations.open_library.work_editions
Full name
open-library.open_library_work_editions
ParameterTypeRequiredDescription
No parameters.
work_ratings Read

Get work ratings.

Lua path
app.integrations.open_library.work_ratings
Full name
open-library.open_library_work_ratings
ParameterTypeRequiredDescription
No parameters.
work_bookshelves Read

Get work bookshelf counts.

Lua path
app.integrations.open_library.work_bookshelves
Full name
open-library.open_library_work_bookshelves
ParameterTypeRequiredDescription
No parameters.
edition Read

Get one edition by ID.

Lua path
app.integrations.open_library.edition
Full name
open-library.open_library_edition
ParameterTypeRequiredDescription
No parameters.
isbn Read

Get an edition by ISBN.

Lua path
app.integrations.open_library.isbn
Full name
open-library.open_library_isbn
ParameterTypeRequiredDescription
No parameters.
books_api Read

Look up books by ISBN, LCCN, OCLC, or OLID bibkeys.

Lua path
app.integrations.open_library.books_api
Full name
open-library.open_library_books
ParameterTypeRequiredDescription
No parameters.
author Read

Get one author by ID.

Lua path
app.integrations.open_library.author
Full name
open-library.open_library_author
ParameterTypeRequiredDescription
No parameters.
author_works Read

List works by an author.

Lua path
app.integrations.open_library.author_works
Full name
open-library.open_library_author_works
ParameterTypeRequiredDescription
No parameters.
subject Read

List works for a subject.

Lua path
app.integrations.open_library.subject
Full name
open-library.open_library_subject
ParameterTypeRequiredDescription
No parameters.
recent_changes Read

List recent Open Library changes.

Lua path
app.integrations.open_library.recent_changes
Full name
open-library.open_library_recent_changes
ParameterTypeRequiredDescription
No parameters.
cover_url Read

Build a cover image URL.

Lua path
app.integrations.open_library.cover_url
Full name
open-library.open_library_cover_url
ParameterTypeRequiredDescription
No parameters.