beatrice

GraphQL API for LLM-powered smart-novel features. The service is model-provider-agnostic — configure it against any OpenAI-compatible endpoint via env vars.

See the repo for setup and self-hosting instructions.

Contact

kasir-barati

https://github.com/kasir-barati/smart-novel-beatrice

API Endpoints

<<url is missing>>

Endpoint

All operations are served at POST /graphql on the deployed instance.

Queries

`healthcheck`

Description

Healthcheck API which returns basic info about the service and if it is running.

Response

Returns a HealthCheck!

Example

Query

query healthcheck {
  healthcheck {
    isRunning
    model
    version
  }
}

Response

{
  "data": {
    "healthcheck": {
      "isRunning": true,
      "model": "qwen2.5:3b",
      "version": "1.0.1"
    }
  }
}

Mutations

`explainWord`

Description

Return a structured explanation of a word as it is used in the given context.

Response

Returns a WordExplanationType!

Arguments

Name	Description
`word` - `NonEmptyTrimmedString!`	The single word to explain.
`context` - `NonEmptyTrimmedString!`	The sentence or paragraph the word appears in — used to disambiguate its meaning.

Example

Query

mutation explainWord(
  $word: NonEmptyTrimmedString!,
  $context: NonEmptyTrimmedString!
) {
  explainWord(
    word: $word,
    context: $context
  ) {
    meaning
    simplifiedExplanation
    synonyms
    antonyms
  }
}

Variables

{
  "word": "impulse",
  "context": "She acted on impulse and booked a flight home the same night."
}

Response

{
  "data": {
    "explainWord": {
      "meaning": "A sudden strong urge to do something impulsive.",
      "simplifiedExplanation": "A quick feeling that makes you want to do something without thinking.",
      "synonyms": ["urge", "whim", "impulse", "instinct"],
      "antonyms": ["hesitation", "deliberation", "restraint"]
    }
  }
}

Mutations

`normalizeTextForTts`

Description

Return an LLM-normalised version of the given text suitable for TTS.

Response

Returns a String!

Arguments

Name	Description
`text` - `NonEmptyTrimmedString!`	Raw text to be normalised for TTS — numbers, acronyms, symbols, and dates are rewritten into the form a speech engine can read aloud naturally.

Example

Query

mutation normalizeTextForTts($text: NonEmptyTrimmedString!) {
  normalizeTextForTts(text: $text)
}

Variables

{"text": "Dr. Smith met with 3 clients at 9am on 12/03/2024."}

Response

{"data": {"normalizeTextForTts": "xyz789"}}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example

true

Types

HealthCheck

Description

Snapshot of service liveness and configured model.

Fields

Field Name	Description
`isRunning` - `Boolean!`	Always true when this resolver executes.
`model` - `String!`	LLM model this service is currently configured to use.
`version` - `String!`	Service version — matches the Docker Hub image tag published from the same commit.

Example

{"isRunning": true, "model": "qwen2.5:3b", "version": "1.0.1"}

Types

NonEmptyTrimmedString

Description

String scalar that trims leading/trailing whitespace and rejects empty or whitespace-only values.

Example

NonEmptyTrimmedString

Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example

"xyz789"

Types

WordExplanationType

Description

Structured explanation of one word as it is used in a specific context.

Fields

Field Name	Description
`meaning` - `String!`	Concise dictionary-style definition of the word as used in context.
`simplifiedExplanation` - `String!`	Same idea expressed for a younger or non-native reader.
`synonyms` - `[String!]!`	Up to five words meaning roughly the same thing.
`antonyms` - `[String!]!`	Up to five words meaning roughly the opposite.

Example

{
  "meaning": "A sudden strong urge to do something impulsive.",
  "simplifiedExplanation": "A quick feeling that makes you want to do something without thinking.",
  "synonyms": ["urge", "whim", "impulse", "instinct"],
  "antonyms": ["hesitation", "deliberation", "restraint"]
}

Documentation by Anvil SpectaQL