@knowzai/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Knowz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/portable/.env.example

@@ -0,0 +1,250 @@
+# Knowz Portable — customer-runnable PULL kit environment template (spec OPS_PortableImageRelease N2).
+# Requires Docker Compose v2.20+ for optional external-service overlays.
+# Copy to `.env` and replace every <CHANGE_ME...> with a REAL value. There are NO committed defaults for
+# secrets: `docker compose -f docker-compose.yml up` fails fast if any required var below is unset
+# (fail-closed ${VAR:?} substitution).
+#
+#   docker login ghcr.io          # with your GHCR_PULL_TOKEN (read:packages) — see the quickstart
+#   cp .env.example .env
+#   # edit .env
+#   docker compose -f docker-compose.yml up -d
+
+# ── Image selection (REQUIRED: KNOWZ_VERSION) ────────────────────────────────────────────────────────
+# KNOWZ_VERSION: the platform release you were given, e.g. 0.2.0 (NO leading `v`). Pins every image.
+KNOWZ_VERSION=<CHANGE_ME_platform_version_e.g_0.2.0>
+# KNOWZ_FLAVOR: leave EMPTY for the default Azure/stub/BYO-OpenAI-compat portable images. Set to `-gcp`
+# ONLY to pull the Google Vertex-flavored api/worker images (see the Google AI section below).
+KNOWZ_FLAVOR=
+
+# ── Postgres ──────────────────────────────────────────────────────────────────────────────────────
+# PG_USER is not secret (defaults to "knowz" if omitted). PG_PASSWORD is REQUIRED.
+PG_USER=knowz
+PG_PASSWORD=<CHANGE_ME_strong_db_password>
+
+# ── MinIO object storage ────────────────────────────────────────────────────────────────────────────
+# Root credentials bootstrap MinIO only. The API/worker use a separate bucket-scoped identity.
+MINIO_ROOT_USER=knowzminio
+MINIO_ROOT_PASSWORD=<CHANGE_ME_strong_minio_password>
+MINIO_APP_ACCESS_KEY=knowzapp
+MINIO_APP_SECRET_KEY=<CHANGE_ME_distinct_strong_minio_application_secret>
+MINIO_BUCKET=knowz-portable
+STORAGE_PROVIDER=MinioS3
+
+# ── External managed backing services (optional; leave commented for bundled defaults) ────────────
+# Each backing service is independent. External PostgreSQL requires max_prepared_transactions>=100
+# (Cloud SQL database flag / RDS parameter group). Initialize its two DBs + extensions idempotently:
+# docker compose -f docker-compose.yml -f docker-compose.external-db-init.yml -f docker-compose.external-db.yml run --rm external-db-init
+# docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d
+# PG_HOST=<managed-postgres-private-host>
+# PG_PORT=5432
+# PG_SSL_MODE=Require                       # Npgsql: Prefer | Require | VerifyFull
+# PG_EXTRA_OPTIONS=;Trust Server Certificate=true  # raw Npgsql suffix; begin with semicolon
+#
+# External S3-compatible storage reuses MINIO_APP_ACCESS_KEY / MINIO_APP_SECRET_KEY as the access-key ID /
+# secret. AWS supports virtual-host style; GCS S3 interoperability requires an HMAC key pair and
+# path-style addressing. Never use a service-account JSON key.
+# S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
+# S3_REGION=us-east-1
+# S3_FORCE_PATH_STYLE=false
+# GCS example: S3_ENDPOINT=https://storage.googleapis.com, S3_REGION=auto, S3_FORCE_PATH_STYLE=true
+#
+# Redis uses a complete StackExchange.Redis connection string, including TLS/auth options.
+# REDIS_CONNECTION_STRING=master.<id>.<region>.cache.amazonaws.com:6379,ssl=true,password=<auth-token>,abortConnect=false
+# REDIS_CONNECTION_STRING=<memorystore-ip>:6378,ssl=true,password=<auth-string>,abortConnect=false
+#
+# Compose any combination. Fully managed + the optional Caddy TLS edge:
+# docker compose -f docker-compose.yml -f docker-compose.external-db.yml -f docker-compose.external-storage.yml -f docker-compose.external-redis.yml -f docker-compose.edge.yml up -d
+
+# ── Auth (REQUIRED) ──────────────────────────────────────────────────────────────────────────────────
+# JWT_SECRET: >= 32 cryptographically-random chars (e.g. `openssl rand -base64 48`).
+JWT_SECRET=<CHANGE_ME_at_least_32_random_chars>
+# CLI-bootstrapped admin-user credentials for the normal web sign-in.
+ADMIN_USERNAME=admin@knowz.local
+ADMIN_PASSWORD=<CHANGE_ME_at_least_12_chars_mixed>
+# SuperAdmin console passphrase. Generate with `openssl rand -base64 32` (or equivalent).
+# SUPERADMIN_PASSPHRASE=
+# Manual Compose bootstrap (run once after the API is healthy):
+# curl -X POST http://localhost:${API_PORT:-5000}/api/v1/bootstrap/admin \
+#   -H "X-Super-User-Key: $SUPERADMIN_PASSPHRASE" -H "Content-Type: application/json" \
+#   -d '{"tenantName":"Knowz Local","adminEmail":"admin@knowz.local","adminPassword":"<strong-password>"}'
+
+# ── MCP service-to-service key (REQUIRED, must match across api + mcp) ───────────────────────────────
+MCP_SERVICE_KEY=<CHANGE_ME_mcp_service_key>
+
+# ── Internal Worker/API event key (REQUIRED, matching value across both containers) ─────────────────
+INTERNAL_API_KEY=<CHANGE_ME_internal_api_key>
+
+# ── Platform organization seed (optional benign defaults) ──────────────────────────────────────────
+# PLATFORM_ORG_SLUG=knowz
+# PLATFORM_ORG_NAME=Knowz
+# An existing initialized database retains its saved organization name; rename it in SuperAdmin or re-initialize.
+
+# ── Provider selection (master + optional per-capability overrides) ─────────────────────────────────
+# KNOWZ__CLOUDPROVIDER=Azure                       # Azure | Gcp | OpenAiCompat
+# KNOWZ__CLOUDPROVIDER__AI=Azure
+# KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE=Azure     # also accepts None
+# KNOWZ__CLOUDPROVIDER__VISION=Azure              # also accepts None
+# KNOWZ__CLOUDPROVIDER__TRANSCRIPTION=Azure       # also accepts None
+
+# ── Azure OpenAI Foundry preset (default portable image flavor) ─────────────────────────────────────
+# AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
+# AZURE_OPENAI_API_KEY=<provider-key>
+
+# ── Embedding (offline by default; zero external calls) ─────────────────────────────────────────────
+# EMBEDDING_PROVIDER=Stub  -> deterministic offline embedder (default; fully offline, CI-friendly).
+# OpenAI direct uses Option A/OpenAiCompat with https://api.openai.com/v1; only Stub is special here.
+# EMBEDDING_DIMENSIONS MUST match the pgvector column dim (1536 for -small/ada, 3072 for -large).
+EMBEDDING_PROVIDER=Stub
+EMBEDDING_MODEL_NAME=text-embedding-3-small
+EMBEDDING_DIMENSIONS=1536
+# OpenAI-direct credentials belong in OPENAICOMPAT__APIKEY under Option A.
+
+# ── AI provider: default is the offline stub (no config below = no external AI calls) ────────────────
+# Pick AT MOST ONE of the two options below. Leaving both unset keeps the zero-network stub.
+
+# ── Option A: BYO OpenAI-compatible endpoint (OpenAI / Together / Ollama / vLLM / LM Studio) ─────────
+# Vendor-neutral — works on the DEFAULT flavor (KNOWZ_FLAVOR empty; no -gcp image needed).
+# ChatModel + EmbeddingModel are REQUIRED when selected (no universal default — boot fails loud). ApiKey
+# is OPTIONAL (local Ollama/vLLM run keyless). EMBEDDINGDIMENSIONS MUST equal EMBEDDING_DIMENSIONS above
+# and the pgvector column dim — local embedding models often emit 384/768; a mismatch fails boot LOUDLY.
+# KNOWZ__CLOUDPROVIDER=OpenAiCompat
+# KNOWZ__CLOUDPROVIDER__AI=OpenAiCompat
+# OPENAICOMPAT__ENDPOINT=https://api.openai.com/v1          # OpenAI direct
+# OPENAICOMPAT__ENDPOINT=http://host.docker.internal:11434/v1   # local Ollama on the host (keyless)
+# OPENAICOMPAT__APIKEY=<optional-only-if-the-endpoint-requires-one>
+# OPENAICOMPAT__CHATMODEL=<required-e.g. gpt-4o-mini OR llama3.1>
+# OPENAICOMPAT__EMBEDDINGMODEL=<required-e.g. text-embedding-3-small OR nomic-embed-text>
+# OPENAICOMPAT__EMBEDDINGDIMENSIONS=1536                    # MUST match EMBEDDING_DIMENSIONS + pgvector col
+
+# ── Option B: Google Vertex AI (Gemini) — requires the -gcp image flavor ─────────────────────────────
+# Two things are needed:
+#   1. Pull the GCP-flavored api/worker images:  set KNOWZ_FLAVOR=-gcp above.
+#   2. Authenticate once on the host with ADC (no service-account key files):
+#         gcloud auth application-default login
+#      then point GCLOUD_ADC_PATH at the ABSOLUTE path of the file it writes and select the Gcp provider.
+# GCLOUD_ADC_PATH=/absolute/path/to/.config/gcloud/application_default_credentials.json  # host ADC (mounted :ro)
+# KNOWZ__CLOUDPROVIDER=Gcp
+# KNOWZ__CLOUDPROVIDER__AI=Gcp
+# The -gcp image currently ships Vertex AI, but not GCP perception modules. Keep those axes disabled:
+# KNOWZ__CLOUDPROVIDER__DOCINTELLIGENCE=None
+# KNOWZ__CLOUDPROVIDER__VISION=None
+# KNOWZ__CLOUDPROVIDER__TRANSCRIPTION=None
+# Azure BYOK perception may be combined with -gcp (Vertex chat + Azure perception): set selected axes to
+# Azure instead of None and configure their vars in the BYOK section below.
+# VERTEX__PROJECT=<your-gcp-project-id>          # REQUIRED when AI provider = Gcp (no default)
+# VERTEX__REGION=us-central1                     # default us-central1
+# Leave VERTEX__CHATMODEL / VERTEX__EMBEDDINGMODEL unset to use platform defaults; empty values are treated as unset.
+# VERTEX__CHATMODEL=google/gemini-2.5-flash
+# VERTEX__EMBEDDINGMODEL=google/gemini-embedding-001
+# VERTEX__EMBEDDINGDIMENSIONS=1536               # MUST match EMBEDDING_DIMENSIONS
+#
+# HONEST embedding reporting under Vertex (CONFIG_PortableEmbeddingProviderEnv): the top-level embedding
+# vars above default to Stub / text-embedding-3-small, which MISreport the live model under Gcp (embeddings
+# still run Vertex — only the labels read by logs / SuperAdmin / search diagnostics are wrong). When selecting
+# Gcp, also set the top-level embedding vars to match the Vertex embedder:
+#   EMBEDDING_MODEL_NAME=google/gemini-embedding-001   # match VERTEX__EMBEDDINGMODEL
+#   EMBEDDING_DIMENSIONS=1536                           # match VERTEX__EMBEDDINGDIMENSIONS + the pgvector column
+# Leave EMBEDDING_PROVIDER as-is — the Gcp master switch selects the Vertex embedder regardless of the token.
+
+# ── Option C: AWS Bedrock via gateway sidecar (optional; default image flavor) ─────────────────────
+# AWS Samples does not publish a public gateway image. Build Dockerfile_ecs from the pinned upstream
+# commit 274b794e2ef6a163327b5dc0720ea2be9bef720e, push it to your ECR, and use that immutable tag here.
+# BEDROCK_GATEWAY_IMAGE=<account>.dkr.ecr.<region>.amazonaws.com/bedrock-access-gateway:274b794e2ef6a163327b5dc0720ea2be9bef720e
+# BEDROCK_GATEWAY_API_KEY=<CHANGE_ME_random_internal_gateway_key>
+# AWS_REGION=us-east-1
+# KNOWZ__CLOUDPROVIDER=OpenAiCompat
+# KNOWZ__CLOUDPROVIDER__AI=OpenAiCompat
+# OPENAICOMPAT__ENDPOINT=http://bedrock-gateway:8080/api/v1
+# OPENAICOMPAT__APIKEY=<same-value-as-BEDROCK_GATEWAY_API_KEY>
+# OPENAICOMPAT__CHATMODEL=<required-Bedrock-chat-model-id>
+# OPENAICOMPAT__EMBEDDINGMODEL=amazon.titan-embed-text-v2:0
+# OPENAICOMPAT__EMBEDDINGDIMENSIONS=1024
+# EMBEDDING_DIMENSIONS=1024
+# Both dimension values must match. The pgvector dimension is fixed at first boot; changing it later
+# requires a database wipe/re-embed. Never mix dimensions in one index.
+
+# ── Option D: Azure OpenAI (BYOK chat + embeddings; default image flavor) ───────────────────────────
+# The explicit AI axis is REQUIRED; use the Azure OpenAI Foundry endpoint/key placeholders above.
+# KNOWZ__CLOUDPROVIDER__AI=Azure
+# AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
+# AZURE_OPENAI_API_KEY=<CHANGE_ME_azure_openai_key>
+# EMBEDDING_MODEL_NAME=<azure-embedding-DEPLOYMENT-name>  # Azure deployment name, not the model ID
+# EMBEDDING_DIMENSIONS=1536                              # MUST match the pgvector column dimension
+# Precedence: explicit AI axis + endpoint/auth beats EMBEDDING_PROVIDER=Stub; keys alone never flip chat off the stub.
+
+# ── Option E: Fully-local embeddings (Qwen3-Embedding-0.6B sidecar) ────────────────────────────────
+# Adds REAL local retrieval embeddings while chat may remain the default canned stub. It also combines
+# with Option D Azure chat or Option A OpenAiCompat chat. Do NOT combine it with Option B/Bedrock (the
+# gateway owns embeddings) or the -gcp flavor (Vertex uses its native embedder and ignores this endpoint).
+# EMBEDDING_PROVIDER=Stub
+# EMBEDDING_ENDPOINT=http://embedder:80/v1
+# EMBEDDING_MODEL_NAME=Qwen/Qwen3-Embedding-0.6B
+# EMBEDDING_DIMENSIONS=1024
+# EMBEDDING_API_KEY=<CHANGE_ME_optional_or_leave_unset>
+# EMBEDDER_IMAGE=ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.1
+# EMBEDDER_MODEL_ID=Qwen/Qwen3-Embedding-0.6B
+# docker compose -f docker-compose.yml -f docker-compose.embedder.yml up -d
+#
+# Option A/OpenAiCompat edge: also set OPENAICOMPAT__EMBEDDINGMODEL=Qwen/Qwen3-Embedding-0.6B and
+# OPENAICOMPAT__EMBEDDINGDIMENSIONS=1024; those inherited keys select its embedding model/dimensions.
+# First boot downloads about 1.2 GB from Hugging Face. That is this option's only egress; the model is
+# cached in the knowz-portable-embeddermodels volume. For air-gap use, pre-seed that volume and set:
+# Sizing: the sidecar defaults are tuned for an 8 GB Docker Desktop VM (EMBEDDER_MAX_BATCH_TOKENS=4096).
+# Single inputs are capped at roughly that token budget; on hosts giving Docker >= 12 GB memory, set
+# EMBEDDER_MAX_BATCH_TOKENS=8192 (or 16384) to embed full-length parent documents.
+# HF_HUB_OFFLINE=1
+# Once the cache is warm, the deployment is fully offline again.
+# Use 1024 dimensions only on a FRESH deployment. An existing 1536-dimensional corpus fails boot loud;
+# reset the database volume or re-embed the entire corpus. Never mix embedding lineages in one column.
+
+# ── BYOK cloud perception (per-axis opt-in) ───────────────────────────────────────────────────────
+# Leave this entire section commented for the zero-egress default. Each cloud axis is independent.
+#
+# Vision — sends images to Azure AI Vision. Your Azure account is billed directly; Knowz does not meter
+# this usage and adds no charge.
+# AZUREAIVISION__ENDPOINT=https://<resource>.cognitiveservices.azure.com/
+# AZUREAIVISION__APIKEY=<CHANGE_ME_azure_vision_key>
+# AZUREAIVISION__FEATURES=<optional-comma-separated-features>
+#
+# Document Intelligence — sends PDFs and documents to Azure Document Intelligence. Your Azure account is
+# billed directly; Knowz does not meter this usage and adds no charge.
+# DOCUMENTINTELLIGENCE__ENDPOINT=https://<resource>.cognitiveservices.azure.com/
+# DOCUMENTINTELLIGENCE__APIKEY=<CHANGE_ME_document_intelligence_key>
+# DOCUMENTINTELLIGENCE__USEMANAGEDIDENTITY=false
+#
+# Whisper transcription — sends audio to Azure OpenAI. Your Azure account is billed directly; Knowz does
+# not meter this usage and adds no charge. Seeded gpt-4o-mini-transcribe and gpt-4o-transcribe-diarize
+# deployment names work without an override; set AZUREOPENAI__WHISPERDEPLOYMENTNAME when yours differs.
+# If no deployment resolves, audio reports `No transcription model configured`. Reuse endpoint/key above.
+# AZUREOPENAI__WHISPERDEPLOYMENTNAME=<CHANGE_ME_whisper_deployment_name>
+# AZUREOPENAI__TRANSCRIPTIONDEPLOYMENTNAME=<optional-transcription-deployment-name>
+# AZUREOPENAI__TRANSCRIPTION__ENDPOINT=https://<resource>.openai.azure.com/
+# AZUREOPENAI__TRANSCRIPTION__APIKEY=<CHANGE_ME_azure_transcription_key>
+#
+# AssemblyAI diarization — sends audio to AssemblyAI. Your AssemblyAI account is billed directly; Knowz
+# does not meter this usage and adds no charge. Realtime provider selection is optional.
+# ASSEMBLYAI__APIKEY=<CHANGE_ME_assemblyai_key>
+# ASSEMBLYAI__ENABLEBATCHPREMIUMTIER=true
+# KNOWZ__CLOUDPROVIDER__REALTIMETRANSCRIPTION=AssemblyAi
+#
+# Face recognition — on-device ONNX through FaceAiSharp (NOT Azure Face). No cloud key, no egress, and no
+# per-item cloud billing; compute runs on your machine. Optional threshold default: 0.68.
+# ENRICHMENT__FACERECOGNITION__ENABLED=true
+# FACERECOGNITION__MATCHTHRESHOLD=0.68
+
+# ── Port mappings (optional) ─────────────────────────────────────────────────────────────────────────
+# API/web/MCP bind to loopback by default. Set 0.0.0.0 only behind a firewall and TLS reverse proxy.
+# Postgres, Redis, and MinIO have no host-published ports; use `docker compose exec` for diagnostics.
+BIND_ADDRESS=127.0.0.1
+# PUBLIC_API_URL=https://api.knowz.example.com
+# PUBLIC_WEB_ORIGIN=https://knowz.example.com
+# PUBLIC_MCP_URL=https://mcp.knowz.example.com
+# API_PORT=5000
+# WEB_PORT=3000
+# MCP_PORT=3001
+
+# ── MCP tuning (optional) ────────────────────────────────────────────────────────────────────────────
+# MCP_BACKEND_MODE=selfhosted
+# MCP_VALIDATE_API_KEY=true
+# Optional expert override for the image registry/namespace.
+# KNOWZ_REGISTRY=ghcr.io/knowz-io