Current runtime, from request to release.

What these docs describe.

Scout is the intelligence and orchestration layer currently used by ProjectHub Recruiter Alpha. The public implementation combines deterministic query/state/evidence handling with a generative language layer and post-generation factual validation.

Evidence order

ProjectHub has moved quickly enough that some checked-in reports describe earlier Ollama-only phases. This documentation uses the following precedence when sources disagree:

1. Executable source and current runtime configuration.
2. Production runtime facts in data/scout-runtime-knowledge.json.
3. Current master/develop documentation when it matches the code it describes.
4. Dated QA, qualification, and handoff reports as historical evidence only.

What is shipped and what is not.

The architecture is being pushed toward portability, but these docs describe the implementation that can be inspected and tested now rather than the intended end state.

Run the current public implementation.

The released browser widget is a single JavaScript artifact hosted on GitHub Pages. Embedding it loads the ProjectHub UI and connects recruiter-style questions to the ProjectHub backend.

<script src="https://bradleymatera.github.io/ProjectHub/ProjectHub.js"></script>

Local repository quickstart

git clone https://github.com/BradleyMatera/ProjectHub.git
cd ProjectHub
npm ci
npm test
npm run eval-retrieval
npm run build
node --check server-gemini.js

Runtime boundaries.

Scout does not send an entire knowledge base to a model and hope the model behaves. Deterministic backend stages prepare the request and evidence first; the model is used for language generation inside that boundary.

How one message is processed.

Local lexical retrieval before generation.

Verified application knowledge is flattened into searchable RAG chunks. Okapi BM25 scores those chunks locally. Context-bearing questions can combine literal, expanded, and rewritten query views using Reciprocal Rank Fusion.

Reproduce the retrieval benchmark

npm run test:retrieval
npm run eval-retrieval

The checked-in 40-query golden set has a documented Recall@6 of 1.000 and MRR@6 of 0.971. CI independently rejects a retrieval run if Recall@6 falls below 0.90. Treat the benchmark as a scoped retrieval measurement, not as an end-to-end answer-accuracy percentage.

Conversation context is server-owned.

The current runtime does not rely only on raw transcript text. It maintains structured session state so follow-ups can refer to previously discussed projects, roles, comparisons, names, and unresolved references.

Semantic constraints before prose.

A response contract describes what an answer is allowed to mean before the final language is generated. This is separate from style or phrasing.

Allowlisted, read-only functions.

The current tool layer gathers structured evidence. It does not expose arbitrary shell execution or write access to external business systems.

Swappable generation behind one router.

The generative boundary lives behind lib/local-model-router.js. Application orchestration calls the router rather than coding directly against one provider.

Cloudflare allocation behavior

The current provider adapter records a Workers AI free allocation of 10,000 neurons/day. That is a shared account allocation, not a per-user allowance. The adapter recognizes allocation exhaustion and does not silently switch to paid-only models.

Generated text is not accepted just because the model returned it.

Scout checks the generated reply against retrieved/structured evidence and the response contract. The validator is responsible for rejecting unsupported factual content, not for making the prose sound nicer.

Prose provenance

Browser integration.

The current ProjectHub frontend is deliberately lightweight: vanilla JavaScript source modules are assembled into one embeddable ProjectHub.js artifact. The widget owns UI/session behavior; the backend remains authoritative for knowledge retrieval, evidence, inference, validation, and structured state.

Current application interface.

The production ProjectHub backend is reachable at https://projecthub-chat.bradleymatera.dev. These endpoints describe the current application implementation; they are not a public multi-tenant API-key/SLA product.

Chat request

{
  "message": "Which project best demonstrates AWS experience?",
  "sessionId": "per-tab-session-id",
  "history": [
    {
      "user": "What is Bradley strongest at?",
      "assistant": "..."
    }
  ]
}

Response fields to inspect

{
  "ok": true,
  "reply": "...",
  "provider": "cloudflare",
  "model": "@cf/meta/llama-3.1-8b-instruct-fast",
  "proseSource": "MODEL_GENERATION",
  "pipeline": ["..."],
  "contract": {
    "intent": "...",
    "directAnswer": "...",
    "factState": "..."
  },
  "agent": {
    "retrievalCandidates": [],
    "selectedEvidence": [],
    "generationCalls": []
  },
  "sessionMemory": {
    "turns": 5,
    "retained": true
  }
}

Inspect what produced the answer.

The runtime exposes enough metadata to distinguish retrieval, generation, validation, model/provider use, build provenance, and usage accounting.

curl https://projecthub-chat.bradleymatera.dev/health
curl https://projecthub-chat.bradleymatera.dev/health/live
curl https://projecthub-chat.bradleymatera.dev/health/ready

Runtime controls.

Production secrets are not committed. The table below documents the important configuration surfaces visible in the current source. Defaults can differ between development examples and deployed production environment values.

Run Scout from the repository.

Cloudflare-backed development

PORT=3000
HOST=127.0.0.1
SCOUT_AGENT_MODE=lite
SCOUT_INFERENCE_PROVIDER=cloudflare
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_MODEL=@cf/meta/llama-3.1-8b-instruct-fast
REQUEST_DEADLINE_MS=15000
GEN_TIMEOUT_MS=12500
USE_BM25_RETRIEVAL=true
RATE_LIMIT_MAX=20

Ollama development/evaluation

ollama pull qwen2.5:1.5b

# .env
SCOUT_AGENT_MODE=lite
SCOUT_INFERENCE_PROVIDER=ollama
OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=qwen2.5:1.5b
REQUEST_DEADLINE_MS=15000
USE_BM25_RETRIEVAL=true

Start and inspect

node server-gemini.js

curl http://127.0.0.1:3000/health/live
curl http://127.0.0.1:3000/health/ready
curl http://127.0.0.1:3000/health

Production-parity container testing.

The repository includes a Docker path intended to make backend/inference testing reproducible without relying on whatever happens to be installed on the host.

docker compose up --build -d

curl http://localhost:3000/health

docker compose run --rm test-runner npm test

Commands that can be rerun.

The documentation avoids turning one historic score into a general quality claim. The useful part is the checked-in test/eval surface and the commands needed to reproduce a result.

CI checks on develop / pull requests

• Production dependency audit at high severity.
• Analytics build and committed bundle freshness.
• ProjectHub.js bundle freshness against source modules.
• Server/workspace/analytics syntax checks.
• Cost-ledger and retrieval unit tests.
• Retrieval evaluation plus a Recall@6 ≥ 0.90 gate.
• Knowledge JSON parse/required-key validation.
• Committed secret-pattern scan.
• Staging-routing guard.

Source, staging, production.

Required sequence

1. Branch from current develop.
2. Run the checks appropriate to the change.
3. Use private preview for backend/agent work when applicable.
4. Open a PR to develop; required CI must pass.
5. Deploy/mirror development staging and verify the actual staging frontend/backend.
6. Open a reviewed release PR into master. The September 5 release used a master-parented commit carrying the qualified develop tree.
7. Deploy/verify production backend, then publish the production frontend.
8. Record and verify the released source commit.

Minimum acceptance

npm test
npm run build
node --check server-gemini.js
git diff --check

# Retrieval / conversation changes
npm run eval-retrieval
PROJECTHUB_API_URL=http://127.0.0.1:<port> npm run eval:local-api
python3 test-production-conversations.py \
  --url http://127.0.0.1:<port>/api/chat \
  --delay 2.5

Start with the failing stage.

Useful diagnostic commands

npm test
npm run eval-retrieval
node --check server-gemini.js
curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/health/ready

Current boundaries.

• Domain: the shipped application is scoped to Bradley Matera's verified professional information and Scout's own runtime, not arbitrary world knowledge.
• Commercial packaging: the released Core already supports empty/no-KB operation; the generalized domain-package system and self-service installation remain productization goals, not released features.
• Inference allocation: the public production path depends on external Cloudflare Workers AI allocation/capacity.
• Application rate control: the current server defaults to 20 chat requests per minute per IP unless deployment configuration overrides it.
• Deadline: requests are bounded; slow/unavailable inference can return a typed technical error instead of an answer.
• Browser inference: WebGPU/client-local work is experimental and is not the normal production generation path.
• State: conversation state is intentionally bounded rather than acting as permanent personal memory.
• Docs/version drift: dated QA/handoff files can describe historical runtime phases; check executable source and current runtime facts before treating them as current configuration.
• No public SLA/API-key platform: the current backend routes document the implementation used by ProjectHub. A generalized customer API product is not claimed here.

Where each behavior lives.