# Langdock + ShinrAI

Protect selected onward model requests, or protect documents before uploading them to Langdock. Connector version **0.1.0**, MIT. Direct installation is available from this source bundle; no marketplace listing is claimed.

**Validation status:** the sandbox HTTPS relay passes real model calls in both reply modes, with streaming. Transport and knowledge-upload failure tests pass. Actual Langdock workspace configuration, BYOK activation, folder indexing and application journeys remain **pending access**. This package is a preview until those checks pass.

## Choose your protection boundary

| Setup | Protected transfer | Original data still present |
| --- | --- | --- |
| Langdock custom model → customer relay → provider | Messages and retrieved text sent to the selected model | Langdock receives text typed in its interface and content already uploaded there |
| Local file → ShinrAI → knowledge upload helper | Protected extracted text or flattened PDF uploaded to Langdock | Your local original is preserved |
| Your application → relay → Langdock Completion API | Supported model messages before Langdock receives them | Your application retains its original input |

The relay supports textual conversations, function tools and their JSON arguments, streaming and follow-ups. It rejects raw image/audio/file payloads and unsupported schema fields. Protect documents separately first. Protocol identifiers and JSON field names must be static schema configuration. Restored tool arguments are for local tools; protect any later external tool transfer separately.

## Protected custom models (BYOK)

1. Obtain your ShinrAI key from the console. Keep your existing model-provider key in the relay configuration. Generate a separate random relay key; this is the only key supplied to Langdock.
2. Copy `relay.env.example` to `relay.env`, fill in the four credentials/model fields and restrict file access: `chmod 600 relay.env`. Build and start: `docker compose up -d --build relay`. This bundle includes the sibling `python` directory needed by the build.
3. Put the relay behind your existing HTTPS ingress. `Caddyfile.example` shows a host Caddy configuration for port 4010. The relay exposes only the two required authenticated API routes publicly. TLS must be valid and publicly reachable.
4. Have BYOK activated for the Langdock workspace. In workspace model settings, add two OpenAI-compatible custom models. Use base URL `https://relay.your-company.example/v1`, the relay key, and model IDs `shinrai-private` and `shinrai-restored`. Name them **ShinrAI – retain pseudonyms** and **ShinrAI – restore replies**. Set the supported context size for your upstream model and disable image input.
5. Test and save each model. Make the intended protected model visible to the relevant users/groups. Inspect model defaults and every configured fallback: use only another protected relay deployment or remove that fallback. A direct provider fallback defeats this protection boundary. Disable external tools in the initial reference configuration.
6. Ask the selected model to repeat `max.mustermann@example.org`. Private mode returns a replacement; restored mode returns the recognized original. Then test a knowledge question, citation, follow-up and a deliberately unavailable relay. The last operation must fail instead of switching to an unprotected model.

Langdock's [endpoint setup](https://docs.langdock.com/en/admin/byok/setup-guides), [activation](https://docs.langdock.com/en/admin/byok/byok-setup), [model visibility](https://docs.langdock.com/en/admin/byok/adding-models) and [fallback configuration](https://docs.langdock.com/en/admin/byok/fallback-models) describe the corresponding workspace controls.

## Protected knowledge uploads

Give the Langdock API key Knowledge Folder API scope and Editor access to the chosen knowledge base. Install the Python connector with `pip install ../python`, set `SHINRAI_API_KEY` and `LANGDOCK_API_KEY` through private environment configuration (or their `_FILE` alternatives), then run:

```sh
shinrai-langdock check
shinrai-langdock upload customer-record.pdf --folder YOUR_FOLDER_ID --format text
shinrai-langdock upload scanned-record.pdf --folder YOUR_FOLDER_ID --format pdf
```

`check` verifies ShinrAI and a synthetic protection example; it does not claim a Langdock workspace connection. Uploads accept TXT, PDF and DOCX, up to 10 MB, 100 pages and 125,000 extracted characters. The default text output works well for knowledge search. PDF output is flattened. Neither original filenames, source URLs nor restoration maps are uploaded. No editable DOCX export is provided. Incomplete processing stops the upload. Temporary ShinrAI jobs are deleted after downloading the protected results; service retention also limits abandoned results to 24 hours.

For Docker, copy `knowledge.env.example` to private `knowledge.env`, put selected files in `input/`, then run `docker compose run --rm knowledge upload /input/customer-record.pdf --folder YOUR_FOLDER_ID`. `upload-folder.sh` provides a batch workflow for explicitly selected local files.

The [knowledge upload API](https://docs.langdock.com/en/developer/knowledge-folder-api/upload-file) is the destination. An interrupted upload may have reached Langdock: inspect the knowledge base before retrying to avoid duplicates. An error does not cause the original to be uploaded.

## Applications calling Langdock

Use a separate relay instance with the Completion API settings shown in `relay.env.example`. Your application's base URL and key point to that local relay. Select one of the two ShinrAI aliases. The relay holds the Langdock API key and calls an administrator-selected Langdock model. Use a supported region and model from your workspace's [Completion API](https://docs.langdock.com/en/developer/completion-api/openai). Do not point a BYOK relay back at a Langdock model that calls that same relay: that creates a routing loop.

## Troubleshooting and QA

401: check which of the three separate keys belongs to the failing connection. 400: inspect unsupported payload fields; never enable unprotected fallback. 503: check ShinrAI connectivity, allowance and key expiry. 502: inspect the configured provider and model; relay errors deliberately exclude customer content. Upload 403: check folder sharing and Editor access. Public connection failure: check TLS, endpoint suffix `/v1`, model visibility and BYOK activation.

QA's working sandbox base URL is `https://api-sbx.shinrai.innovius.io/integrations/langdock/v1`; its private relay key is referenced in the secure handoff. `reports/langdock03-endpoint.json` records endpoint evidence separately from the pending workspace gate. No simulated Langdock screenshot is supplied. Capture workspace screenshots and record its release date/version when access becomes available.