Sentence Knowledge Parser

Turn any sentence into a structured map of word-, phrase-, and sentence-level language knowledge.

Version: 0.9.0

Sentence Knowledge Parser is an API for decomposing a sentence into very fine-grained, teachable language knowledge units. It is built for language-learning products, curriculum tooling, content authoring, learning analytics, and diagnostic workflows.

Given one sentence or a short text, the API can return:

• direct language knowledge contained in the text;
• knowledge grouped by observation scale: w_L-bit, ph_L-bit, and s_L-bit;
• optional prerequisite knowledge, when the caller provides their own LLM configuration;
• human-readable cards explaining what each knowledge point means.

This public repository contains API documentation, an OpenAPI schema, a TypeScript client, and Node.js examples. It does not contain the private parser implementation, scoring logic, prompt templates, registry data, dependency generation logic, deployment files, or internal definitions.

What It Does

The API analyzes language at three observation scales:

Public count type	Observation scale	What it observes	Example
w_L-bit	word-level	knowledge carried by a specific word	how as a degree marker; the as a definite article
ph_L-bit	phrase-level	knowledge carried by a small meaning group	how good; the goal; is good
s_L-bit	sentence-level	knowledge carried by a sentence or clause pattern	How good the goal is! as an exclamative pattern

These three types are not merged into one score. They are counted separately because their learning weight is different.

Complete Example

Input:

How good the goal is!

Example direct knowledge:

Object in the sentence	Type	Human-readable knowledge point
How	w_L-bit	how marks degree in an exclamation
good	w_L-bit	adjective meaning a positive quality
the	w_L-bit	definite article marking a specific object
the goal	ph_L-bit	noun phrase used as the subject
How good	ph_L-bit	degree phrase placed before the rest of the sentence
How good the goal is!	s_L-bit	exclamative sentence pattern

Example count shape:

{
  "lbit_count_by_type": {
    "direct": { "w": 20, "ph": 8, "s": 3 },
    "prerequisite": { "w": 18, "ph": 10, "s": 5 },
    "cumulative": { "w": 38, "ph": 18, "s": 8 }
  }
}

cumulative.w = direct.w + prerequisite.w, and the same rule applies separately to ph and s.

Direct-only Request

Direct analysis does not require a caller LLM key. It returns the knowledge points directly observed in the input text.

curl -X POST https://lbit.bczabcd.cn/api/v1/analyze \
  -H "Authorization: Bearer YOUR_SENTENCE_KNOWLEDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "How good the goal is!",
    "language": "en",
    "return_lbits": true,
    "return_parse": true
  }'

Example response excerpt:

{
  "text": "How good the goal is!",
  "language": "en",
  "analysis_status": "full_parse",
  "cache_status": "miss",
  "lbit_count_by_type": {
    "direct": { "w": 20, "ph": 8, "s": 3 },
    "prerequisite": { "w": 0, "ph": 0, "s": 0 },
    "cumulative": { "w": 20, "ph": 8, "s": 3 }
  },
  "human_lbit_summary": {
    "lbit_cards": [
      {
        "source": "direct",
        "type": "w_L-bit",
        "object": "How",
        "name_zh": "程度标记",
        "plain_explanation_zh": "原句里的 How 表示“多么/多大程度”。"
      }
    ]
  }
}

TypeScript Client

import { SentenceKnowledgeClient } from "@bczabcd/sentence-knowledge-parser";

const client = new SentenceKnowledgeClient({
  apiKey: process.env.SENTENCE_KNOWLEDGE_API_KEY!
});

const result = await client.analyze({
  text: "How good the goal is!",
  language: "en",
  return_lbits: true,
  return_parse: true
});

console.log(result.lbit_count_by_type.direct);

Full Prerequisite Analysis

Prerequisite generation may call an LLM. Public API users must provide their own model configuration. The service does not use the service owner's LLM key for public API calls.

import { SentenceKnowledgeClient } from "@bczabcd/sentence-knowledge-parser";

const client = new SentenceKnowledgeClient({
  apiKey: process.env.SENTENCE_KNOWLEDGE_API_KEY!
});

const job = await client.createPrerequisiteJob({
  text: "How good the goal is!",
  language: "en",
  return_lbits: true,
  return_parse: true,
  llm: {
    provider: "openai_compatible",
    base_url: "https://ark.cn-beijing.volces.com/api/v3",
    model: process.env.CALLER_LLM_MODEL!,
    api_key: process.env.CALLER_LLM_API_KEY!
  }
});

const completed = await client.waitForPrerequisiteJob(job.job_id);
console.log(completed.prerequisite_summary);

If llm.api_key or llm.model is missing, the prerequisite job endpoint returns LLM_CONFIG_REQUIRED.

Caller-owned LLM keys should be sent from your backend server, not from browser-side code.

Authentication

All /api/v1/* endpoints require an API key. API keys are issued to invited users only. This repository documents API usage; it is not a public self-service account portal.

Authorization: Bearer YOUR_SENTENCE_KNOWLEDGE_API_KEY

You can also use:

X-Lbit-Api-Key: YOUR_SENTENCE_KNOWLEDGE_API_KEY

Supported Languages

Current API language values:

en, ja, es

API Reference

See docs/API.md and openapi.yaml.