@lucern/sdk 0.2.0-alpha.1

package/README.md

@@ -0,0 +1,97 @@
+# @lucern/sdk
+
+TypeScript SDK for the Lucern reasoning platform.
+
+## Package status
+
+- Distribution target: private/internal registry
+- License: UNLICENSED
+- Auth model: service principal key via `LUCERN_API_KEY`
+
+## Install
+
+```bash
+export NODE_AUTH_TOKEN="<your-package-token>"
+cat <<'EOF' > .npmrc
+@lucern:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+EOF
+
+npm install @lucern/sdk
+```
+
+## Quickstart
+
+```ts
+import { createLucernClient } from "@lucern/sdk";
+
+const lucern = createLucernClient({
+  apiKey: process.env.LUCERN_API_KEY,
+  baseUrl: process.env.LUCERN_BASE_URL ?? process.env.LUCERN_API_BASE_URL,
+});
+
+const projectList = await lucern.context.listProjects({ includeShared: true });
+const project = projectList.data.projects[0];
+
+if (!project?.projectId) {
+  throw new Error(
+    "No graph project is available. Bootstrap or create one before running the SDK quickstart."
+  );
+}
+
+const belief = await lucern.beliefs.create({
+  canonicalText:
+    "AI-native reasoning infrastructure will expand rapidly over 3 years",
+  projectId: project.projectId,
+});
+
+await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
+  confidence: 0.72,
+  trigger: "evidence_added",
+  rationale: "Two independent sources confirm demand pull.",
+});
+```
+
+## Surface
+
+`createLucernClient()` returns grouped clients:
+
+- `beliefs`
+- `evidence`
+- `questions`
+- `graph`
+- `judgments`
+- `worktrees`
+- `context`
+- `tasks`
+- `research`
+- `tools` (runtime custom tool registration/invocation)
+- `custom` (default custom namespace invoker)
+- `extensions` (dynamic namespace invokers)
+- `raw` (low-level endpoint clients)
+
+## Custom tool extensions
+
+```ts
+import { z } from "zod";
+
+lucern.tools.register({
+  namespace: "stack",
+  name: "score_deal",
+  description: "Stack-specific scoring extension",
+  inputSchema: z.object({ dealId: z.string() }),
+  outputSchema: z.object({ score: z.number() }),
+  handler: async ({ dealId }) => ({ score: dealId.length / 10 }),
+});
+
+await lucern.extensions.stack.score_deal({ dealId: "deal_001" });
+```
+
+## Key provisioning endpoints
+
+SDK key lifecycle methods map to:
+
+- `GET /api/platform/v1/identity/keys`
+- `POST /api/platform/v1/identity/keys`
+- `POST /api/platform/v1/identity/keys/{keyId}/rotate`
+- `POST /api/platform/v1/identity/keys/{keyId}/revoke`