Skip to content

quickstart.md

Latest commit

 

History

History
168 lines (116 loc) · 6.15 KB

quickstart.md

File metadata and controls

168 lines (116 loc) · 6.15 KB
Raw

Quickstart

This guide shows the shortest path from a folder of documents to a named CANON corpus you can query and evaluate.

1. Run Tests

python -m pytest

2. Run The Built-In Demo

python -m canon.product.demo

The demo runs the AI infrastructure fixture end to end: ingest, grounded brief, automated brief evaluation, alert digest, alert evaluation, review packet, and handoff summary. A successful automated run ends with automated_pass_human_review_required, because final quality still needs human labels.

If CANON is installed as a package, the same command is available as:

canon-demo

3. Prepare A Local Corpus Folder

Use a local folder, mounted Google Drive folder, or local git checkout.

Recommended first test:

data/my_docs/
  memo.md
  sources.csv
  briefing.pdf
  notes.docx

Do not include secrets, private keys, .env files, credentials, or files you do not want indexed into local artifacts.

4. Create A Project Boundary

python -m canon.product.project --project-name "AI Infrastructure Geopolitical Risk" --domain "AI infrastructure and geopolitical risk" --regions "Latin America,Brazil,Chile,Mexico" --languages "English,Spanish,Portuguese" --issue-categories "energy demand,water and cooling,cloud dependency,sovereign AI" --report-types "weekly_intelligence_brief,regional_risk_report,alert_digest" --source-boundaries "G:\My Drive\CANON Corpus" --corpus-id ai_infra_geo_risk_corpus

This writes reports/projects/<project_id>/project_config.json and .md. The config records the domain ontology, monitored regions/languages, issue categories, desired reports, source/corpus boundary, and the rule that monitors must not run without an explicit source boundary.

5. Profile The Source

python -m canon.ingest.flexible --input data/my_docs --mode my_topic_v1 --profile-only

For a mounted folder:

python -m canon.product.mounted_corpus --input "G:\My Drive\CANON Corpus" --mode my_topic_v1 --profile-only

For a local git checkout:

python -m canon.product.mounted_corpus --input "C:\path\to\repo" --mode repo_review_v1 --profile-only

6. Ingest And Build A Corpus

python -m canon.ingest.flexible --input data/my_docs --mode my_topic_v1
python -m canon.corpus.build --corpus-id my_topic_v1_corpus --from-modes my_topic_v1 --corpus-only

The mounted-corpus helper can do the same workflow:

python -m canon.product.mounted_corpus --input "G:\My Drive\CANON Corpus" --mode my_topic_v1 --corpus-id my_topic_v1_corpus --domain my_domain

Generated raw/processed artifacts are written under data/. Generated reports are written under reports/. Both locations are gitignored.

7. Query Through The API

Start the API:

python -m canon.product.server --host 127.0.0.1 --port 8000

Health check:

Invoke-WebRequest http://localhost:8000/health

See available routes and example request bodies:

Invoke-RestMethod http://localhost:8000/v1/routes

Create the same project boundary through the API:

Invoke-RestMethod -Method Post http://localhost:8000/v1/projects/start -ContentType "application/json" -Body '{"project_name":"AI Infrastructure Geopolitical Risk","domain":"AI infrastructure and geopolitical risk","regions":["Latin America","Brazil","Chile","Mexico"],"languages":["English","Spanish","Portuguese"],"issue_categories":["energy demand","water and cooling","cloud dependency"],"desired_report_types":["weekly_intelligence_brief","alert_digest"],"source_boundaries":["G:/My Drive/CANON Corpus"]}'

Ask for evidence:

Invoke-RestMethod -Method Post http://localhost:8000/v1/evidence-packets -ContentType "application/json" -Body '{"request_id":"req_001","project_id":"my_project","question":"What does this corpus say about grid risk?","mode":"my_topic_v1_corpus","evidence_requirements":{"top_k":10,"include_conflicts":true,"include_source_diversity":true,"include_query_diagnostics":true}}'

Check whether retrieved evidence visibly covers the frame you asked for:

python -m canon.product.frame_coverage "What does this corpus say about grid risk?" --mode my_topic_v1_corpus --top-k 10
Invoke-RestMethod -Method Post http://localhost:8000/v1/frame-coverage -ContentType "application/json" -Body '{"question":"What does this corpus say about grid risk?","mode":"my_topic_v1_corpus","research_frame":{"subdomains":["energy","water"],"regions":["Latin America"],"languages":["English","Spanish"]},"evidence_requirements":{"top_k":10,"minimum_source_types":["official","local_media"]}}'

Frame coverage is diagnostic. It highlights missing dimensions and follow-up queries, but human review is still required before treating coverage as complete.

For the intended Drive-first workflow, use the private corpus as the first evidence source, then allow external expansion only when you want corroboration, freshness checks, or gap filling. See drive_first_rag.md.

8. Run The Pre-Human Gate

python -m canon.product.prehuman_check --mode my_topic_v1_corpus --benchmark-id llm_judged_my_topic_v1 --judge-provider heuristic --model-providers local --rerankers heuristic --top-k 10 --candidate-k 25

This is an automated triage gate. It does not replace human qrels or final answer review.

9. Check Product Readiness

python -m canon.product.readiness --mode social_science_ir_v1_harvest10
python -m canon.product.final_check --mode ai_infra_geo_risk_demo --records reports/intelligence_brief_review_tasks_ai_infra_geo_risk_demo.json --no-fail

blocked_human_review is an expected final-check status before human labels are complete. It means the automated gates are separate from final acceptance.

Troubleshooting

If the API returns not_found, the server is usually running but the path or HTTP method is wrong. Check the route list:

Invoke-RestMethod http://localhost:8000/v1/routes

The error response also includes available_routes for the method you used. Most product actions are POST routes with JSON bodies; health and route discovery are GET routes.