backlot 0.0.0__tar.gz

backlot-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrekkyLab
+
+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.

backlot-0.0.0/PKG-INFO

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: backlot
+Version: 0.0.0
+Summary: A read-only mock of enterprise SaaS knowledge APIs, served over your own corpus with per-document ACLs
+Author-email: khj809 <onsealeatang@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brekkylab/backlot
+Project-URL: Repository, https://github.com/brekkylab/backlot
+Project-URL: Issues, https://github.com/brekkylab/backlot/issues
+Keywords: mock,rag,slack,gmail,google-drive,jira,confluence,github,notion,s3,amazon-s3,hubspot,linear,graphql,benchmark
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: httpx>=0.27
+Requires-Dist: graphql-core>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff~=0.15.22; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: httpx>=0.27; extra == "examples"
+Requires-Dist: slack_sdk>=3.27; extra == "examples"
+Requires-Dist: PyGithub>=2.3; extra == "examples"
+Requires-Dist: atlassian-python-api>=3.41; extra == "examples"
+Requires-Dist: google-api-python-client>=2.120; extra == "examples"
+Requires-Dist: google-auth>=2.29; extra == "examples"
+Requires-Dist: notion-client>=3.1; extra == "examples"
+Requires-Dist: boto3>=1.34; extra == "examples"
+Requires-Dist: hubspot-api-client>=12; extra == "examples"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Requires-Dist: anthropic[mcp]>=0.40; extra == "mcp"
+Requires-Dist: openai>=1.40; extra == "mcp"
+Requires-Dist: openai-agents>=0.1; extra == "mcp"
+Requires-Dist: pyyaml>=6.0; extra == "mcp"
+Requires-Dist: fastmcp>=2.0; extra == "mcp"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-readers-slack>=0.5; extra == "llamaindex"
+Requires-Dist: llama-index-readers-google>=0.7; extra == "llamaindex"
+Requires-Dist: llama-index-readers-github>=0.11; extra == "llamaindex"
+Requires-Dist: llama-index-readers-jira>=0.6; extra == "llamaindex"
+Requires-Dist: llama-index-readers-confluence>=0.7; extra == "llamaindex"
+Requires-Dist: llama-index-readers-notion>=0.5; extra == "llamaindex"
+Requires-Dist: llama-index-readers-s3>=0.6; extra == "llamaindex"
+Requires-Dist: llama-index-readers-linear>=0.5; extra == "llamaindex"
+Requires-Dist: jira>=3.10; extra == "llamaindex"
+Requires-Dist: atlassian-python-api>=4.0; extra == "llamaindex"
+Requires-Dist: slack_sdk>=3.43; extra == "llamaindex"
+Requires-Dist: google-api-python-client>=2.198; extra == "llamaindex"
+Requires-Dist: google-auth>=2.55; extra == "llamaindex"
+Requires-Dist: boto3>=1.40; extra == "llamaindex"
+Requires-Dist: s3fs>=2026.6; extra == "llamaindex"
+Provides-Extra: mirage
+Requires-Dist: mirage-ai[fuse]~=0.0.4; extra == "mirage"
+Dynamic: license-file
+
+# Backlot
+
+[![tests](https://github.com/brekkylab/backlot/actions/workflows/ci.yml/badge.svg)](https://github.com/brekkylab/backlot/actions/workflows/ci.yml)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A **read-only** mock server that stands in for a whole stack of enterprise SaaS knowledge sources
+at once.
+It speaks each service's real read API — the exact response shapes, pagination schemes, auth,
+and native permission endpoints their official SDKs expect — over a corpus **you** supply, so a
+RAG/search connector built on those SDKs can be exercised **end-to-end** without the live
+services.
+
+## Quickstart
+
+```bash
+pip install backlot
+```
+
+That puts the `backlot` command on PATH. A server needs a corpus, and one is bundled with the
+package — 136 documents covering every source it serves — so there is nothing to fetch or write:
+
+```bash
+backlot import --bundled    # the bundled corpus -> data/mock.sqlite + data/tokens.yaml
+backlot serve               # http://127.0.0.1:8000
+curl -s localhost:8000/health
+```
+
+Or skip the CLI entirely and let a test spin one up on a free port, serving that same corpus
+(`pip install "backlot[examples]"` for the vendor SDKs the first snippet uses):
+
+```python
+import backlot
+from slack_sdk import WebClient
+
+with backlot.mock_server() as m:                       # no arguments: the bundled corpus
+    slack = WebClient(token=m.token, base_url=f"{m.base_url}/slack/api/")
+    print(slack.conversations_list()["channels"])
+
+with backlot.mock_server(records=[                     # or your own records, inline
+    {"source_type": "confluence", "space": "handbook", "title": "On-call",
+     "content": "Page for Sev1 and Sev2 only.", "author_email": "ava@acme.com"},
+]) as m:
+    ...
+```
+
+`python -m backlot` is the same CLI as the `backlot` script, for when the venv is not activated.
+Working on Backlot itself instead of with it? [CONTRIBUTING.md](CONTRIBUTING.md) covers the
+from-source install.
+
+### Docker
+
+```bash
+docker build -t backlot .                  # server + the bundled corpus baked in; no download
+docker run -p 8000:8000 backlot
+curl -s localhost:8000/health
+```
+
+That image answers every endpoint of every source out of the box. Use
+`--target serve` for a server with **no** corpus, for a deployment that mounts its own
+`/app/data`.
+
+## Why you need this
+
+Connectors are easy to write and hard to trust. Proving one works means an account with every
+vendor, an OAuth app per vendor, seeded data in each, and rate limits between you and every retry —
+so most of it
+gets tested against fixtures that agree with your assumptions instead of with the API. Backlot is
+the API: same shapes, same pagination, same permission endpoints, over documents you control.
+
+It is the right tool when you are:
+
+- **building or upgrading a connector** — crawl a source to exhaustion, then diff what you got
+  against what you loaded, on a corpus small enough to reason about
+- **testing ACL-scoped retrieval** — every document carries its own readers, and each user's token
+  sees only theirs, so "does this leak" is a test rather than an audit
+- **running that suite in CI** — no accounts, no secrets, no network, no flakes from someone else's
+  outage; a server starts in a second and dies with the test
+- **evaluating RAG or agents** — point an SDK, an MCP server, or a LlamaIndex reader at it and get
+  the same answers on every run, because ids and timestamps are derived, not random
+- **reproducing a bug you cannot reach** — a paginated edge case, an odd MIME type, an empty thread:
+  write the document that causes it and serve it in seconds
+
+It is **not** a sandbox for writes, a rate-limit or latency simulator, or a source of realistic
+*content* — the documents are yours.
+
+## Preparing a corpus
+
+The server reads a corpus from `data/` (`mock.sqlite` + `tokens.yaml`). Build it from your own
+documents, or load a public dataset.
+
+You describe each document the way its own service would, and a per-source JSON Schema says what
+that record may carry. `title` and `content` are served verbatim; so is every other field you set —
+authors, timestamps, threads, comments, labels, states, ACLs — so no part of a response *has* to be
+synthesized. What you leave out is filled in **deterministically**, each value hashed from the
+stable key it belongs to (a document's `doc_id`, a container's name, an author's address), so ids
+never move between calls or pages.
+
+### Bring your own corpus
+
+One JSONL document per line, validated against a per-service JSON Schema
+([`backlot/schemas/`](backlot/schemas/)), then loaded:
+
+```bash
+backlot import mycorpus.jsonl              # validate + load -> data/
+backlot import mycorpus.jsonl --dry-run    # validate only, no DB writes
+backlot import mycorpus.jsonl --roster roster.yaml   # state the principals, don't derive them
+backlot import corpus.jsonl.gz             # gzipped, read as a stream
+backlot import artifact-dir/               # a sharded corpus + its manifest, digests verified
+```
+
+```json
+{"source_type": "slack", "channel": "incidents", "author_email": "bob@acme.com", "content": "Anyone seeing 502s from the gateway?", "replies": [{"content": "Looking now.", "author_email": "ava@acme.com"}]}
+{"source_type": "gmail", "mailbox": "ceo", "title": "Q1 board deck draft", "content": "Draft narrative for the Q1 board meeting.", "author_email": "ceo@acme.com", "to": "ava@acme.com", "readers": ["ceo@acme.com", "ava@acme.com"]}
+```
+
+Only `source_type` and `content` are required (`title` too, for every source except Slack). Where
+to look next:
+
+| To learn | Read |
+|---|---|
+| every field a record may carry | [`examples/bring-your-own-corpus/sample_corpus.jsonl`](examples/bring-your-own-corpus/sample_corpus.jsonl) — the field reference, and a test keeps it exhaustive |
+| the rules each source imposes | [`backlot/schemas/README.md`](backlot/schemas/README.md) |
+| import → serve → query, runnable | [`examples/bring-your-own-corpus/run.py`](examples/bring-your-own-corpus/run.py) |
+
+The schemas double as the contract for **LLM dataset generation**: hand one to a model as a
+structured-output schema, generate records, then `--dry-run` before loading. See
+[`backlot/schemas/README.md`](backlot/schemas/README.md).
+
+### Load a public dataset
+
+[EnterpriseRAG-Bench](https://github.com/onyx-dot-app/EnterpriseRAG-Bench) is ~500k synthetic
+enterprise documents across nine of the supported sources. One command downloads, loads and
+ACL-derives it:
+
+```bash
+backlot import --type enterpriserag-bench    # -t erb for short
+```
+
+What that dataset does and does not carry, and how to redistribute it as BYO-JSONL, is in
+[`examples/import-enterpriserag-bench/`](examples/import-enterpriserag-bench/) — it is one corpus
+you can load, not part of this server's contract.
+
+## Auth & tokens
+
+Each service authenticates its own way, and the mock expects what the real one does: a bearer token
+for most, HTTP Basic for Jira/Confluence, a **bare** `Authorization` value for Linear's personal API
+keys, SigV4 for S3, and Google's OAuth token exchange for a connector carrying a client config.
+
+You construct none of it. Two mock-only endpoints hand out every credential the corpus generated —
+an admin/service token that bypasses the ACL (use it to crawl), plus one identity per person, each
+seeing only what their own ACL permits:
+
+```bash
+curl -s localhost:8000/_mock/users
+```
+```json
+{ "org": "acme", "admin_token": "admin-service-token", "count": 10,
+  "admin_s3_access_key_id": "AKIA732S…", "admin_s3_secret_access_key": "l4sz5sXT…",
+  "users": [{ "email": "ava.chen@acme.com", "name": "Ava Chen", "token": "usr-29b84da570…",
+              "s3_access_key_id": "AKIADNLO…", "s3_secret_access_key": "0FdhlUUQ…",
+              "groups": ["engineering", "handbook", "product", "design"] }] }
+```
+
+```bash
+curl -s localhost:8000/_mock/credentials    # for a Google client that wants a config, not a token
+```
+```json
+{ "org": "acme", "token_uri": "http://localhost:8000/oauth2/token",
+  "oauth_client": { "client_id": "e8ae7a….apps.googleusercontent.com", "client_secret": "GOCSPX-…" },
+  "service_account": { "type": "service_account", "client_email": "…", "private_key": "…" } }
+```
+
+Use a user's `token` and every API filters to that user, which is what makes per-user access a test
+rather than an audit. `token_uri` points back at the mock, so a client library's own refresh lands
+here and resolves to the same ACL — a user's refresh_token is just their bearer token. Both
+endpoints serve credentials in the clear, so `BACKLOT_EXPOSE_TOKENS=false` closes them; the same
+values are in `data/tokens.yaml`. Per-service detail:
+[`examples/using-official-sdk/`](examples/using-official-sdk/).
+
+## Example Usages
+
+Every one of these points a real client at the mock's base URL — that is the only change from
+talking to the live service.
+
+### Official SDKs
+
+```python
+from slack_sdk import WebClient
+WebClient(token=TOKEN, base_url="http://localhost:8000/slack/api/")
+
+from github import Github, Auth
+Github(auth=Auth.Token(TOKEN), base_url="http://localhost:8000/github")
+
+from atlassian import Jira, Confluence
+Jira(url="http://localhost:8000/atlassian", username="svc@x", password=TOKEN)
+Confluence(url="http://localhost:8000/atlassian/wiki", username="svc@x", password=TOKEN)
+
+from googleapiclient.discovery import build
+from google.api_core.client_options import ClientOptions
+from google.oauth2.credentials import Credentials
+creds = Credentials(token=TOKEN)
+build("gmail", "v1", credentials=creds, client_options=ClientOptions(api_endpoint="http://localhost:8000"))
+build("drive", "v3", credentials=creds, client_options=ClientOptions(api_endpoint="http://localhost:8000/drive/v3"))
+
+from notion_client import Client
+Client(auth=TOKEN, base_url="http://localhost:8000/notion")   # SDK appends /v1/ itself
+
+import boto3
+from botocore.config import Config
+boto3.client("s3", endpoint_url="http://localhost:8000/s3", aws_access_key_id=AK, aws_secret_access_key=SK,
+             region_name="us-east-1", config=Config(s3={"addressing_style": "path"}))
+```
+
+A runnable, self-contained script per service is in [`examples/using-official-sdk/`](examples/using-official-sdk/).
+
+### MCP
+
+An MCP server pointed at the mock retrieves through it, ACL-scoped to whatever token it
+authenticates with. Some vendors publish a server that takes a base URL — use it directly:
+
+```python
+# examples/using-mcp-with-agents/atlassian.py — the community-official mcp-atlassian, over Docker.
+# The host must end in .atlassian.net for the server's Cloud detection, so alias it at the mock.
+params = StdioServerParameters(command="docker", args=[
+    "run", "-i", "--rm", "--add-host=mock.atlassian.net:host-gateway",
+    "-e", "JIRA_URL=http://mock.atlassian.net:8000/atlassian",
+    "-e", "CONFLUENCE_URL=http://mock.atlassian.net:8000/atlassian/wiki",
+    "-e", "JIRA_USERNAME=svc@example.com", "-e", "CONFLUENCE_USERNAME=svc@example.com",
+    "-e", f"JIRA_API_TOKEN={token}", "-e", f"CONFLUENCE_API_TOKEN={token}",  # a user token -> its ACL
+    "-e", "MCP_ALLOWED_URL_DOMAINS=atlassian.net", "-e", "READ_ONLY_MODE=true",
+    "ghcr.io/sooperset/mcp-atlassian:latest", "--transport", "stdio",
+])
+```
+
+For the ones that don't — GitHub, Slack, Gmail, Drive, HubSpot — a generic **OpenAPI→MCP bridge**
+turns the mock's own typed `/openapi.json` into tools instead (`GET /_mock/openapi/<source>` serves
+the per-source slice):
+
+```python
+# examples/using-mcp-with-agents/github.py — no vendor SDK, no vendor MCP server
+params = StdioServerParameters(command=sys.executable, args=[
+    "examples/using-mcp-with-agents/_openapi_bridge.py",
+    "--source", "github", "--base-url", mock.base_url, "--token", mock.token,
+])
+```
+
+Either way an agent then calls `session.list_tools()` and retrieves. Runnable agents for both LLM backends (Anthropic + OpenAI), one file per service, are in [`examples/using-mcp-with-agents/`](examples/using-mcp-with-agents/).
+
+### LlamaIndex readers
+
+Point official [LlamaIndex readers](https://docs.llamaindex.ai/en/stable/module_guides/loading/connector/)
+(`llama-index-readers-*`) at the mock and load an enterprise corpus as `Document` objects — the
+first step of a LlamaIndex ingestion/RAG pipeline.
+
+```python
+from llama_index.readers.github import GitHubIssuesClient
+GitHubIssuesClient(github_token=TOKEN, base_url="http://localhost:8000/github")
+
+from llama_index.readers.confluence import ConfluenceReader
+ConfluenceReader(base_url="http://localhost:8000/atlassian/wiki", cloud=False, api_token=TOKEN)
+```
+
+One runnable script per source is in [`examples/using-llamaindex-readers/`](examples/using-llamaindex-readers/).
+
+
+### Mirage
+
+[mirage](https://github.com/strukto-ai/mirage) mounts a SaaS backend as a **virtual
+filesystem** an agent reads with shell commands (`ls`, `cat`, `grep`, `find`). Point its resources at the mock and you can drive a mirage agent over your corpus offline.
+
+```python
+from mirage import MountMode, Workspace
+from mirage.resource.slack import SlackConfig, SlackResource
+
+resource = SlackResource(SlackConfig(token=TOKEN, base_url="http://localhost:8000/slack/api"))
+ws = Workspace({"/slack": resource}, mode=MountMode.READ)
+await ws.execute("ls /slack/channels/")        # then cat a channel's dated chat.jsonl
+```
+
+One runnable script per source plus a `unified.py` that greps
+across Slack/Gmail/Google Drive at once are in [`examples/using-mirage/`](examples/using-mirage/).
+
+
+## Endpoints (read-only)
+
+| Prefix | Service | Endpoints |
+|---|---|---|
+| `/slack/api` | Slack | `conversations.list` (+`types`; this corpus has no DMs, so `im`/`mpim` select nothing, and an unknown value is `invalid_types`), `conversations.history` (+`oldest`/`latest`/`inclusive`), `conversations.replies`, `conversations.members` (per-channel, paginated), `users.list`, `users.info`, `auth.test`, `api.test` (auth-free connectivity check), `search.messages` |
+| `/gmail/v1` | Gmail | `users/{u}/messages` (+`q`: free text / `from:` `to:` `subject:` `after:` `before:` `newer_than:` `older_than:` `label:` `has:attachment`), `messages/{id}` (`format=full\|metadata\|minimal`), `messages/{id}/attachments/{id}`, `threads` (+`q`), `threads/{id}`, `labels`, `profile`. Message and thread ids are Gmail-shaped — 16 lowercase hex under 2^63, sharing one id space as the real API does — and map back to the corpus document; an id the real API could not parse is refused the same way |
+| `/drive/v3` | Drive | `files` (`q`: `fullText contains`, `name contains`, `mimeType`, `… in parents` incl. `'root'`, `trashed`, `modifiedTime`, `sharedWithMe`, `… in owners`; `orderBy`: `name`/`name_natural`/`createdTime`/`modifiedTime`/`recency`/`folder`/`starred`/`quotaBytesUsed`/`sharedWithMeTime` (+` desc`); `fields` projection, validated), `files/{id}` (+`fields`), `files/{id}/export`, `files/{id}/permissions`, `drives`, `about` (`fields` **required**, as in real Drive; `storageQuota` is measured from the caller's visible corpus). Folders are files here: they match `mimeType='…folder'`, project, sort and resolve permissions like stored rows. Trashed files are excluded unless `trashed = true` asks for them |
+| `/docs/v1`, `/sheets/v4`, `/slides/v1` | Docs/Sheets/Slides | `documents/{id}`, `spreadsheets/{id}`, `presentations/{id}` — native-doc content for editor-aware clients (read structurally instead of via Drive export). `spreadsheets/{id}` returns structure only — cells need `includeGridData=true` (+ optional `ranges`), as in real Sheets. Sheets also serves `spreadsheets/{id}/values/{range}` and `spreadsheets/{id}/values:batchGet` (A1 ranges incl. `Sheet1!A1:B2`, `A:A`, `1:3`, `A2:B`, a bare sheet name quoted or not; `majorDimension`, `valueRenderOption`). A spreadsheet row is one stored **line**, held in a single cell verbatim — the mock picks no column delimiter, so splitting (CSV, pipes, …) stays the corpus owner's decision. Reading a file of the wrong type through any of the three APIs is refused, as real Google does, not reinterpreted |
+| `/github` | GitHub | `search/issues` (`q`: free text + `repo:` `is:` `state:` `type:` `label:` `author:`), `orgs/{org}`, `orgs/{org}/repos`, `repos/{o}/{r}`, `.../issues[/{n}]`, `.../issues/{n}/comments`, `.../pulls[/{n}]`, `.../pulls/{n}/reviews`, `.../readme`, `.../contents[/{path}]`, `.../git/trees/{ref}`, `.../git/blobs/{sha}`, `.../branches/{branch}`, `.../commits/{sha}`, `.../collaborators`, `.../teams`, `orgs/{org}/teams` |
+| `/atlassian/rest/api/3` | Jira | `search/jql` (JQL `project =`, `text\|summary\|description ~`), `issue/{key}`, `issue/{key}/comment`, `field`, `issueLinkType`, `project/search`, `project/{key}/role[/{id}]`, `serverInfo` (also under `rest/api/2`) |
+| `/atlassian/wiki/rest/api` | Confluence | `content`, `content/{id}`, `content/{id}/child/comment`, `content/{id}/restriction/byOperation`, `search` (CQL), `space`, `space/{key}`, `space/{key}/permission` |
+| `/notion/v1` | Notion | `search`, `pages/{id}`, `blocks/{id}`, `blocks/{id}/children`, `databases/{id}` (version-aware), `data_sources/{id}`, `data_sources/{id}/query`, `databases/{id}/query` (legacy), `users[/{id}]`, `users/me`, `comments` |
+| `/hubspot/crm/v3`, `/hubspot/crm/v4` | HubSpot | `objects/{objectType}` (+`limit` max 100, `after`, `properties`, `archived`), `objects/{objectType}/{id}`, `objects/{objectType}/search` (`filterGroups` OR-ed, `filters` AND-ed, 13 operators over any property), `objects/{objectType}/batch/read`, `v4/objects/{type}/{id}/associations/{toType}` |
+| `/s3` | Amazon S3 | `ListBuckets`, `HeadBucket`, `GetBucketLocation`, `ListObjectsV2` (`prefix`/`delimiter`/`continuation-token`), `GetObject` (+`Range`), `HeadObject` |
+| `/linear/graphql` | Linear | **GraphQL only** (one `POST`): `issues`, `issue(id:)` (UUID *or* `ENG-123`), `team(id:)` (UUID, key, or name), `teams`, `comments`, `users`, `viewer`, plus the `Team.issues` / `Issue.{comments,labels,children,relations,inverseRelations,attachments,releases}` connections and the by-id roots (`user`, `workflowState`, `project`, `issueLabel`, `cycle`, `release`, `attachment`, `issueRelation`) the official SDK's lazy relation accessors call. Relay pagination (`first`/`after`, `last`/`before` → `{nodes, pageInfo}`), server-side `filter` compiled into SQL, and full introspection |
+| `/fireflies/graphql` | Fireflies | **GraphQL only** (one `POST`): `transcripts`, `transcript(id:)`, `user[(id:)]`, `users`. Offset pagination — `limit` (**max 50**, clamped) / `skip`, returning a **bare list**, not a Relay connection — plus the documented filters: `keyword` × `scope` (`title`\|`sentences`\|`all`), `fromDate`/`toDate`, `host_email`, `organizers`, `participants`, `user_id`, `mine`, `channel_id`. Field names are snake_case, as Fireflies' own schema has them. Full introspection |
+
+Mock-only endpoints: `/health`, `/_mock/users`, `/_mock/credentials`, `/_mock/openapi/<source>`,
+`/openapi.json`.
+
+## Tests
+
+```bash
+pytest              # unit (synth/pagination/acl/schema/importer parsers) + HTTP endpoint tests
+                    # (full-crawl completeness, content round-trip, ACL enforcement)
+ruff check . && ruff format --check .
+```
+
+## Configuration
+
+Every setting is an env var with a `BACKLOT_` prefix, and a `.env` file in the working directory is
+read too. Defaults are what the server uses when the var is unset.
+
+| Env var | Default | What it does |
+|---|---|---|
+| `BACKLOT_DATA_DIR` | `./data` (resolved against the cwd, **not** the install location) | Where the corpus lives: `mock.sqlite`, `tokens.yaml`, `credentials.yaml`. Both `backlot import` and `backlot serve` read it, which is how you keep several corpora side by side — `BACKLOT_DATA_DIR=/tmp/demo backlot import c.jsonl` |
+| `BACKLOT_ADMIN_TOKEN` | `admin-service-token` | The token that bypasses ACL filtering — a full-crawl / service identity. Set it to anything for a shared deployment |
+| `BACKLOT_ENFORCE_ACL` | `true` | When `false`, any well-formed token is treated as admin. The ACL is still *exposed* through each vendor's permission endpoints, just not *enforced* — useful for isolating whether a connector's gaps are permissions or parsing |
+| `BACKLOT_EXPOSE_TOKENS` | `true` | Serves `GET /_mock/users` and `GET /_mock/credentials`, which hand out every user's token in the clear. Fine for a local mock; set `false` to close both |
+| `BACKLOT_ORG_NAME` | inferred from the corpus (fallback `example`) | The org slug that shows up in `auth.test`, synthesized emails and self-URLs. Inferred from the dominant author email domain — `@acme.com` documents serve as org `acme` — so set it only to override that |
+| `BACKLOT_ORG_DOMAIN` | inferred from the corpus (fallback `example.com`) | The domain half of the same inference, e.g. `acme.com`. Used for addresses the corpus does not state |
+| `BACKLOT_DEFAULT_PAGE_SIZE` | `100` | Page size when a request names none |
+| `BACKLOT_MAX_PAGE_SIZE` | `1000` | Ceiling a request may ask for. Per-vendor caps still win where the real API has one (Fireflies clamps to 50, HubSpot to 100) |
+| `BACKLOT_SQLITE_MMAP_MB` | `256` | Memory-maps the DB so reads come from the OS page cache instead of a syscall each — the main lever against a slow first request after idle. SQLite maps `min(this, db size)`; raise it to at or above your DB size to map a big corpus fully |
+| `BACKLOT_SQLITE_CACHE_MB` | `64` | SQLite's own page cache, per serving connection |
+| `BACKLOT_SQLITE_BUSY_MS` | `5000` | How long a read waits for a lock instead of erroring, so reads ride through an out-of-band write (e.g. an in-place FTS rebuild) rather than 500ing |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: fidelity to the real APIs is the point,
+so a divergence is a bug — measure against the real service, and bring a test that fails without
+your fix.
+
+## License
+
+[MIT](LICENSE)