@kindgi/sdk 0.0.0-bootstrap.0 → 0.1.0

package/skills/kindgi-python-getting-started/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: kindgi-python-getting-started
+description: >
+  Getting a Python Kindgi pack running: what a pack is, scaffolding one
+  (`kindgi init <name> --template=python`) or adding `[tool.kindgi]` to
+  an existing Python app, `uv sync`, `kindgi dev`, the first agent run,
+  connecting a real model, flows, calling the Kindgi API from Python
+  (`kindgi.client`), and building an image. Load this when a Python
+  project has no `[tool.kindgi]` table yet and the user asks to "add
+  Kindgi", "make an agent", "set up a pack", or when you are orienting
+  in a Python pack (pyproject.toml with `[tool.kindgi]`) for the first
+  time. Authoring tools, guardrails and agents is covered by
+  kindgi-python-authoring-tools, kindgi-python-authoring-guardrails and
+  kindgi-python-authoring-agents; models by kindgi-authoring-providers.
+type: core
+library: "kindgi (Python)"
+version: "0.1.0"
+sdk_version: "0.0.0"
+pack_languages: [python]
+sources:
+  - sdks/python/README.md
+  - sdks/python/src/kindgi/pack/config.py
+  - sdks/python/src/kindgi/pack/discovery.py
+---
+
+# Getting started with Kindgi in Python
+
+> **Running `kindgi`:** a Python pack has no Node project, so the
+> `kindgi` CLI (a Node 22+ program) is the one on `PATH`. Python
+> commands run in the pack's environment: `uv run …`.
+
+## What a pack is
+
+A **pack** is a project Kindgi indexes and runs. Its config is the
+`[tool.kindgi]` table of `pyproject.toml`; its primitives live in four
+folders, one or more per `.py` file, at module level:
+
+- **Tools** (`tools/*.py`, `@tool`) — your Python code an agent or flow
+  calls.
+- **Guardrails** (`guardrails/*.py`, `@guardrail`) — checks over an
+  agent's turn.
+- **Agents** (`agents/*.py`, `Agent(...)`) — data: instructions, tools,
+  capabilities. The model runs in Kindgi.
+- **Flows** (`flows/*.py`, `Flow(...)`) — data: steps (tool or agent
+  nodes) and the edges between them.
+
+Kindgi runs the tools and checks in the pack's own Python process (the
+pack service) and calls them over HTTP; everything else runs in the
+Kindgi runtime. A module whose name starts with `_` is a helper, not a
+primitive; `test_*.py`, `*_test.py` and `conftest.py` are skipped.
+
+## Scaffold a new pack
+
+```sh
+kindgi init my-pack --template=python
+cd my-pack
+uv sync            # .venv with the kindgi package
+uv run pytest
+kindgi dev         # boots Kindgi locally and runs this pack, reloading on save
+```
+
+`kindgi dev` needs Postgres: it starts one in Docker unless
+`KINDGI_DATABASE_URL` points at yours. It runs the pack with
+`.venv/bin/python` (or `dev.python` in `[tool.kindgi]`, e.g.
+`["uv", "run", "python"]`), checks that interpreter can import
+`kindgi`, and swaps the code on every save.
+
+## Add Kindgi to an existing Python app
+
+In the app's directory (where its `pyproject.toml` is):
+
+```sh
+kindgi init            # --pack-id=<id> if the app's name doesn't make one
+uv sync                # or what it prints for Poetry / pip
+kindgi dev
+```
+
+`kindgi init` edits the app's `pyproject.toml` in place — your layout and
+comments stay — appending the `[tool.kindgi]` tables (the pack id from
+`[project].name`, or `[tool.poetry].name` in a Poetry 1 app; discovery
+under `kindgi/`; in a Poetry app, `dev.python` runs `poetry run python`)
+and adding `kindgi` to `[project].dependencies`; where it can't edit the
+dependencies (Poetry 1, `dynamic`), it prints the command to run. It adds the `kindgi/tools`,
+`guardrails`, `agents` and `flows` folders, these skills and `.gitignore`
+entries. An app with a `package.json` too gets a TypeScript pack unless you
+pass `--template=python`.
+
+The pack root is on `sys.path`, so tools import the app's own packages by
+name (`from acme.text import normalize`); inside `kindgi/`, import the pack's
+modules relatively. Don't add an `__init__.py` to `kindgi/` — the folder
+would then shadow the `kindgi` package. `kindgi dev` reads the app's `.env`
+/ `.env.local` — keys already there reach the tools as environment
+variables.
+
+## Layout of the template
+
+```
+my-pack/
+├── pyproject.toml                     # [tool.kindgi] — id, version, (discovery, dev, environments)
+├── tools/echo.py, tools/greet.py      # @tool
+├── guardrails/response_not_empty.py   # @guardrail
+├── agents/echo_agent.py               # Agent(...)
+├── flows/echo_flow.py                 # Flow(...)
+├── tests/test_tools.py                # the tools and the check, called directly
+├── README.md
+└── .claude/skills/                    # these skills (`kindgi skills sync` refreshes them)
+```
+
+The `[tool.kindgi]` keys are the ones `kindgi.config.ts` takes —
+`pack`, `discovery`, `dev`, `env`, `environments` — spelled the same.
+
+## First run
+
+With `kindgi dev` running, from another terminal in the pack directory:
+
+```sh
+kindgi runs start --agent=my-pack.echo-agent --input='{"userMessage":"Ada"}'
+```
+
+The answer comes from `dev-echo`, a **fallback** provider a new pack
+gets: no model, no key — it calls the first tool and replies "Tool
+responded: …", and the turn carries a `fallback-provider` warning. For
+a real model, put the key in `.env` and register a provider:
+
+```sh
+kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt
+kindgi providers register --preset=anthropic
+```
+
+It takes over at the next turn. Details and other providers:
+`kindgi-authoring-providers`.
+
+`uv run python -m kindgi.pack index --pack-dir .` prints what Kindgi
+sees (the index); `kindgi dev` reports a broken file with its path and
+keeps serving the rest.
+
+## Flows
+
+A flow is data: nodes and edges (`flow.schema.json`). A node's `ref` may
+be the `Tool` object:
+
+```python
+# flows/record.py
+from kindgi import Flow
+
+from ..tools.ledger import record_expense
+
+record = Flow(
+    id="acme.ledger.record-flow",
+    version="0.1.0",
+    nodes=[{"id": "record", "kind": "tool", "ref": record_expense}],
+    edges=[
+        {"id": "e-start", "from": "$start", "to": "record"},
+        {"id": "e-end", "from": "record", "to": "$end"},
+    ],
+)
+```
+
+A node gets its single upstream node's output (the run input after
+`$start`), or what its `inputMapping` says: each key a `{"literal": …}`
+or a `{"path": …}` rooted at `runInput`, `state` or
+`nodeOutputs.<nodeId>`. The indexer checks every flow against the
+schema. Run one with `kindgi runs start --flow=<id> --input='{…}'`;
+branches, loops and agent steps → `kindgi-python-authoring-flows`.
+
+## Calling Kindgi from Python
+
+`kindgi.client` covers the whole API:
+
+```python
+from kindgi.client import Kindgi
+
+client = Kindgi()  # KINDGI_API_URL + KINDGI_API_TOKEN, or Kindgi(url, token=…)
+run = client.runs.start(agent="my-pack.echo-agent", input={"userMessage": "Ada"})
+print(run.status, run.output["response"]["content"])
+for event in client.runs.stream(str(run.id)):
+    print(event.kind)
+```
+
+`AsyncKindgi` is the asyncio twin. `kindgi dev` prints the URL and the
+token; `.kindgirc.json` in the pack holds them for the CLI.
+
+## Build an image
+
+`kindgi build --env=<name>` (an `[tool.kindgi.environments.<name>]`
+block) builds the pack's image. Its dependencies install from the pack's
+lockfile, frozen, main dependencies only: `uv.lock` (run `uv lock`
+first), or in a Poetry app `poetry.lock` (`poetry lock`; the image brings
+its own pinned Poetry). The index is built in the image; the pack service
+is its entrypoint. An app with only `requirements.txt` can't build yet.
+
+Debian packages the code needs (OCR, PDF tools, `libmagic`, …) are
+declared in `pyproject.toml`; the image installs them, for the build and
+at run time:
+
+```toml
+[tool.kindgi.image]
+system-packages = ["tesseract-ocr", "poppler-utils"]   # names, or name=version
+```
+
+The variables the code reads from `os.environ` (a database URL, a bucket)
+are declared too, names only. A deployed pack service missing a `required`
+one isn't ready, and its `/readyz` names it:
+
+```toml
+[tool.kindgi.env]
+required = ["DATABASE_URL"]
+optional = ["SENTRY_DSN"]
+```
+
+A `[tool.uv] required-version` that excludes the image's uv stops the
+build before anything uploads, with the range to use.
+
+## Two things need the human
+
+- **The pack id and version** in `[tool.kindgi.pack]`. The id prefixes
+  every primitive (`<pack-id>.<name>`); pick it once.
+- **Model credentials.** Ask for the key; never invent or hard-code one.
+
+## Next
+
+- A tool → `kindgi-python-authoring-tools`.
+- A guardrail → `kindgi-python-authoring-guardrails`.
+- An agent → `kindgi-python-authoring-agents`.
+- A flow → `kindgi-python-authoring-flows`.
+- A real model → `kindgi-authoring-providers`.
+- An external resource (a database) for the coding agent →
+  `kindgi-authoring-mcp-servers`.
+
+## Keeping skills up to date
+
+`kindgi skills sync` refreshes `.claude/skills/` from the CLI's copy
+(local edits are kept unless `--force`); `kindgi dev` says when they are
+out of date.
+
+## When the framework itself is the problem
+
+If the bug is in Kindgi or the `kindgi` package and not in the pack's
+code, load `kindgi-framework-feedback` and file it with
+`kindgi feedback write`.

package/src/build.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/build` — a TypeScript pack image's build extensions, for
+ * `image` in `kindgi.config.*` (`systemPackages`, `extensions`,
+ * `buildEnv`).
+ *
+ * Re-exports `@kindgi/handler-runtime/build-extensions` verbatim.
+ */
+
+export { defineBuildExtension, prisma } from '@kindgi/handler-runtime/build-extensions';
+export type {
+  BuildExtension,
+  BuildStep,
+  ImageConfig,
+  PrismaExtensionOptions,
+} from '@kindgi/handler-runtime/build-extensions';

package/src/client.ts

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/client` — client callsite surface.
+ *
+ * Re-exports `createClient` plus every resource-client type, the error
+ * surface, transport primitives, and streaming helpers from the
+ * `@kindgi/client` package (`sdks/typescript/` in this repository).
+ * Names preserved verbatim.
+ *
+ * This sub-path intentionally does NOT re-export the branded ID types
+ * (`AgentId`, `RunId`, etc.) that `@kindgi/client` also happens to
+ * surface — those live in `@kindgi/sdk/types` to keep the flat barrel
+ * (`import { ... } from '@kindgi/sdk'`) collision-free.
+ *
+ * Callsite examples target
+ * `import { createClient } from '@kindgi/sdk/client'`.
+ *
+ * @module @kindgi/sdk/client
+ */
+
+// ---- Client factory + top-level shape ----
+export { createClient } from '@kindgi/client';
+export type { KindgiClient } from '@kindgi/client';
+
+// ---- Resource client types + per-resource input shapes ----
+export type {
+  AdapterConfigureInput,
+  AdapterFilter,
+  AdapterTestInput,
+  AdaptersClient,
+  AddMembershipInput,
+  AgentsClient,
+  ApplyProposalInput,
+  ApprovalFilter,
+  ApprovalsClient,
+  ArtifactFilter,
+  ArtifactsClient,
+  AuditClient,
+  AuditExportInput,
+  BatchDecideInput,
+  BudgetsClient,
+  CapabilitiesClient,
+  CapabilityFilter,
+  ClientOptions,
+  CompleteTokenInput,
+  ConversationFilter,
+  ConversationsClient,
+  CostClient,
+  DecideInput,
+  DraftProposalsInput,
+  EventsClient,
+  FactsClient,
+  FlowFilter,
+  FlowsClient,
+  FlowValidateResult,
+  GuardrailFilter,
+  GuardrailsClient,
+  LogsClient,
+  McpClient,
+  McpEndpointFilter,
+  McpEndpointsClient,
+  TeamMembershipsClient,
+  MemoryClient,
+  MessageFilter,
+  ObservationFilter,
+  ObservationsClient,
+  OrgsClient,
+  PackFilter,
+  PacksClient,
+  PageFilter,
+  PatternsInput,
+  PoliciesClient,
+  PolicyListFilter,
+  PolicyVersionsFilter,
+  ProposalDryRunInput,
+  ProposalListInput,
+  ProposalsClient,
+  ProvenanceClient,
+  ProvenanceExportInput,
+  ProviderFilter,
+  ProvidersClient,
+  ReflectReviewInput,
+  RegistryClient,
+  RegistryFilter,
+  ResumeRunInput,
+  ReviewerFilter,
+  ReviewersClient,
+  RollbackProposalInput,
+  Run,
+  RunsClient,
+  SchedulesClient,
+  SessionsClient,
+  StartRunInput,
+  SubmitForReviewInput,
+  SubscriptionsClient,
+  SupervisorClient,
+  ListTeamsFilter,
+  TeamsClient,
+  TenantClient,
+  TenantConfigClient,
+  TokenFilter,
+  TokensClient,
+  ReinstateToolVersionResult,
+  ToolFilter,
+  ToolVersionFilter,
+  ToolsClient,
+  Transport,
+  TransportRequest,
+  UsageClient,
+  UsageSummaryInput,
+  UserFilter,
+  UsersClient,
+  WebhooksClient,
+  WithdrawProposalInput,
+} from '@kindgi/client';
+
+// ---- Error surface ----
+export { KindgiApiError, fromWire, notImplementedInPreview, notYetWired } from '@kindgi/client';
+export type {
+  AuthError,
+  ConflictError,
+  GuardrailViolation,
+  GuardrailViolationError,
+  InvalidRequestError,
+  NetworkError,
+  NotFoundError,
+  NotImplementedInPreviewError,
+  NotYetWiredError,
+  RateLimitedError,
+  ServerError,
+  KindgiError,
+} from '@kindgi/client';
+
+// ---- Streaming helpers (SSE parser + resume) ----
+export { readSse, unwrapSseData } from '@kindgi/client';
+export type { SseEvent, SseReadOptions } from '@kindgi/client';
+
+// ---- Following a run (browser-safe: a page follows a run with a public token) ----
+export { followRun, subscribeToRun } from '@kindgi/client';
+export type {
+  FollowRunOptions,
+  RunProgress,
+  RunProgressEvent,
+  SubscribeToRunOptions,
+} from '@kindgi/client';

package/src/define.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/define` — pack authoring surface.
+ *
+ * Re-exports the authoring primitives from the individual packages
+ * (`@kindgi/tools`, `@kindgi/guardrails`, `@kindgi/agents`,
+ * `@kindgi/flow`, `@kindgi/schema`) verbatim — no renaming, no
+ * behavior. Consumers reading those packages' docs find matching
+ * symbols here.
+ *
+ * The SDK facade is the recommended public developer surface. The
+ * individual packages remain importable directly.
+ *
+ * @module @kindgi/sdk/define
+ */
+
+// ---- Tools ----
+export {
+  defineTool,
+  defineToolAsync,
+  invokeTool,
+  registerToolSpecSynthesizer,
+} from '@kindgi/tools';
+export type {
+  DefinedTool,
+  DefineToolSpec,
+  HttpAuthSpec,
+  HttpHeaderSpec,
+  HttpMethod,
+  HttpRequestBodySpec,
+  HttpToolSpec,
+  InferInput,
+  InferOutput,
+  Tool,
+  ToolContext,
+  ToolManifest,
+  ToolSecretRef,
+  ToolSpec,
+  ToolSpecSynthesizer,
+} from '@kindgi/tools';
+
+// ---- Guardrails (checks) ----
+export { defineCheck } from '@kindgi/guardrails';
+export type { DefineCheckSpec, DefinedCheck, InferCheckConfig } from '@kindgi/guardrails';
+
+// ---- Agents ----
+export { defineAgent } from '@kindgi/agents';
+export type { Agent, DefineAgentSpec } from '@kindgi/agents';
+
+// ---- Flow ----
+//
+// `defineFlow` is the author-facing primitive that mirrors `defineTool`
+// / `defineCheck` / `defineAgent` — a thin wrapper over `loadFlow` that
+// runs the same validation gauntlet and returns `Result<Flow,
+// FlowError>`. Pack authors reach for `defineFlow` in TypeScript;
+// `loadFlow` remains the wire-form entry point for JSON coming off disk
+// / network.
+export { defineFlow } from '@kindgi/flow';
+export type {
+  EdgePolicy,
+  FanoutNode,
+  Flow,
+  FlowSpec,
+  LoopNode,
+  SubflowNode,
+} from '@kindgi/flow';
+
+// ---- Zod-optional helpers ----
+//
+// Direct access for callers that prefer to convert / inspect schemas
+// themselves rather than let `defineTool` / `defineCheck` do it implicitly.
+export { isZodSchema, toJSONSchema } from '@kindgi/schema';
+export type { AnySchema, ZodLikeSchema } from '@kindgi/schema';

package/src/index.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk` — public developer facade.
+ *
+ * Flat barrel that re-exports the three sub-paths for callers who prefer
+ * a single import: `import { defineTool, createClient, type RunId } from
+ * '@kindgi/sdk'`.
+ *
+ * Sub-paths are the primary developer-facing shape (`@kindgi/sdk/define`,
+ * `@kindgi/sdk/client`, `@kindgi/sdk/types`); this barrel is a
+ * convenience alias.
+ *
+ * @module @kindgi/sdk
+ */
+
+export * from './define.js';
+export * from './client.js';
+export * from './types.js';

package/src/types.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/types` — branded IDs, framework-wide result envelope,
+ * pagination, refs, temporal + version primitives.
+ *
+ * Re-exports types from `@kindgi/types` under their own names. These
+ * are the workspace-wide identifiers callers pass across the SDK
+ * boundary.
+ *
+ * The /types sub-path is where branded identifiers live in the public
+ * facade.
+ *
+ * @module @kindgi/sdk/types
+ */
+
+export type {
+  BlobRef,
+  Brand,
+  ContentHash,
+  Cursor,
+  DatasetRef,
+  DurationMs,
+  ErrOf,
+  Filter,
+  IsoDuration,
+  OkOf,
+  Page,
+  Result,
+  SchemaMajor,
+  Semver,
+  SignatureValue,
+  Timestamp,
+  VersionedRef,
+} from '@kindgi/types';
+
+// ---- Branded IDs ----
+//
+// Re-exported individually rather than via `export type *` so the flat
+// barrel (`import { RunId } from '@kindgi/sdk'`) can see them —
+// `verbatimModuleSyntax` requires named type re-exports for `export *`
+// forwarding to work through the barrel.
+export type {
+  AgentId,
+  ApiTokenId,
+  ApprovalId,
+  ArtifactId,
+  AuditBundleId,
+  ComplianceEvidenceId,
+  ConversationId,
+  DatasetId,
+  EdgeId,
+  EventId,
+  FactId,
+  FixProposalId,
+  FlowId,
+  InstallationId,
+  GuardrailId,
+  KeyId,
+  LogEntryId,
+  NodeId,
+  ObservationId,
+  OrgId,
+  PackId,
+  PolicyId,
+  ProjectId,
+  ProvenanceId,
+  ProviderId,
+  ReviewerId,
+  RunId,
+  ScheduleId,
+  SessionId,
+  SigningKeyId,
+  SubscriptionId,
+  SupervisorId,
+  TeamId,
+  TenantId,
+  ThreadId,
+  ToolId,
+  TriggerId,
+  UserId,
+  WaitTokenId,
+  WebhookDeliveryId,
+  WebhookId,
+} from '@kindgi/types';

package/src/webhooks.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/webhooks` — receiving Kindgi's webhooks. Server only: it
+ * uses `node:crypto`, so it stays out of `/client` (browser-safe) and the
+ * flat barrel.
+ *
+ * Re-exports the Standard Webhooks helpers from `@kindgi/crypto`:
+ * `verifyWebhook` for a receiver, `generateWebhookSecret` for the secret an
+ * app registers by name, and `signWebhook` / `webhookHeaders` to test a
+ * receiver.
+ *
+ * @module @kindgi/sdk/webhooks
+ */
+
+export {
+  DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+  generateWebhookSecret,
+  isStrongWebhookSecret,
+  signWebhook,
+  verifyWebhook,
+  WEBHOOK_HEADERS,
+  WEBHOOK_SECRET_MIN_BYTES,
+  WEBHOOK_SECRET_PREFIX,
+  webhookHeaders,
+} from '@kindgi/crypto';
+export type {
+  SignWebhookInput,
+  VerifyWebhookFailure,
+  VerifyWebhookInput,
+  VerifyWebhookResult,
+  WebhookRequestHeaders,
+} from '@kindgi/crypto';