Carrick

Carrick turns field progress reports into traceable proposals for updating an infrastructure project schedule. Supervisors can describe work in familiar language; planners retain control over uncertain matches and exported schedule changes.

This repository contains a runnable application and its design documentation. It supports project accounts, supervisor/planner roles, XER or CSV schedule import, typed notes, logs, document and voice capture, planner decisions, and approved progress exports. Optional cloud or local RAG retrieves imported activities and proposes existing TASK IDs. Updated XER output preserves schedule structure and passes a parser round trip; a validated change set is also available. Independent Oracle P6 import remains an external acceptance check. OCR, handwriting, speech, and local AI require separately provisioned engines.

Run locally

Requires Python 3.11 or newer. Basic text and CSV workflows need no package installation.

python3 -m services.api.app

Open http://127.0.0.1:8765 for the interactive introduction, or go to http://127.0.0.1:8765/app for the workspace. The introduction previews matching against a synthetic schedule without saving notes. On first use, create your owner account in the workspace. Existing local schedules and reports belong to that owner’s initial project. Select Load sample project, capture a field update, review it, and create an export. Use Project access to add supervisor or planner accounts. SQLite, source files, and backups remain under ignored data/private/. The server binds to localhost; shared hosting requires the HTTPS configuration described in access, output, and recovery.

Enable AI analysis

The ignored .env file is ready for your OPENAI_API_KEY. Set CARRICK_AI_MODE=openai and restart the server. The report composer then offers AI-assisted matching. This mode sends the note and retrieved schedule activity snippets to OpenAI; the key stays on the local server. The model proposes events and TASK IDs, while a planner confirms every actual date and activity before export. The rule-based mode remains available.

AI uses OpenAI embeddings for retrieval and a structured model response for extraction and reranking. To use a dedicated local cross-encoder for reranking instead, install the optional package and set CARRICK_RERANKER=cross_encoder in .env:

python3 -m venv .venv
.venv/bin/pip install -r requirements-ai.txt
.venv/bin/python -m services.api.app

For legacy selectable-text PDF imports, install requirements-documents.txt. The reviewed document upload path, including scanned pages and diary photos, uses requirements-capture.txt plus locally installed Tesseract; handwriting additionally needs a local vision model. .eml and .txt imports need no extra package. See AI architecture for safeguards and model setup.

Compare rule-based and AI results on the synthetic evaluation set after adding a key:

.venv/bin/python -m scripts.evaluate_matching --ai

The small synthetic set is a development check, not a claim of production accuracy.

Run the checks with:

python3 -m unittest discover -s tests -v

Scans, voice, offline use, and forecasting

The workspace adds editable OCR page previews, microphone recording and transcript correction, device-local drafts and an outbox, and Schedule insights with duration scenarios, float, WBS summaries, dependency conflicts, and an illustrative P50/P80 envelope. Source scans and recordings stay linked to submitted reports.

See capture and offline setup for package installation, local model provisioning, supported inputs, data storage, API contracts, and forecasting assumptions. .env.example includes the local model settings. After provisioning, start the local AI profile with .venv/bin/python -m scripts.run_offline. Standard matching and analytics do not require an LLM.

Restart the Python server after updates so endpoints and additive migrations load. Regression and browser suites exercise capture with deterministic OCR/speech/AI adapters and Chrome’s fake microphone device. They do not measure real engine accuracy or performance. See verification suites.

Report reliability and evaluation

Exact repeat reports retain their sources in one group without repeat inference. Similar wording is flagged for review. Date conflicts, competing claims, all four dependency types, lags, missing actuals, graph cycles, and stale schedule decisions are checked again before approval/export. Progress history adds activity, discipline, status, date, and source filters, pagination, grouped source evidence, and decision details.

The repository includes independent-label export, accuracy/coverage/latency/cost evaluation, and guarded routing-policy calibration. These tools have not been run for this change; no production performance or calibrated-threshold result is claimed. A larger independently reviewed dataset is still required. See reliability and calibration setup. .env.example adds optional CARRICK_ROUTING_POLICY; leave it blank until a validated artifact exists. Restart the local API to apply the additive schema changes.

Access and recovery

Project membership is enforced on the API, including source downloads, approvals, imports, and exports. Supervisors submit reports; planners approve schedule actuals. Accepted report payloads and capture originals are retained before inference. Saved reports support bounded retries and explicit standard-matching fallback; failed captures support manual transcription. Device storage is separated by account and project. See access, output, and recovery.

Intended product loop

1. Import a versioned schedule and index its activities, WBS, locations, and relationships.
2. Accept a text report or discipline spreadsheet and extract activity-level progress events.
3. Suggest schedule activity matches, using schedule context to improve ranking.
4. Clarify ambiguous reports or send them to planner review.
5. Stage validated actuals, preserve the source evidence, and export approved progress records.
6. Retain a structured progress history for later analysis.

Repository map

Path	Responsibility
apps/web/	Supervisor capture and planner review interface
services/api/	HTTP API, orchestration, authorization, and transactional writes
services/worker/	Import, extraction, matching, AI retrieval, and document text ingestion
packages/contracts/	Shared request, event, and export contracts
data/samples/	Public, synthetic fixtures only
infra/	Local and deployment configuration
tests/	Contract, integration, and evaluation suites
docs/	Product, architecture, research, and decision records

Start with the documentation index, then read the product scope, system architecture, and brand guide.

Repository rules

• Keep source reports, customer schedules, credentials, and local research PDFs outside the repository.
• Commit only synthetic or explicitly cleared sample data.
• Treat matching output as a proposal. The system of record changes only through a validated, auditable schedule export or an approved integration.
• Do not claim a matching accuracy, confidence probability, or format compatibility until it is measured.