canisend 0.2.0b2__py3-none-any.whl

canisend/__init__.py

@@ -0,0 +1,3 @@
+"""Academic application preparation CLI package."""
+
+__version__ = "0.2.0b2"

canisend/cli.py

@@ -0,0 +1,426 @@
+from pathlib import Path
+
+import typer
+
+from canisend.evidence import extract_profile_evidence
+from canisend.examples import run_packaged_example
+from canisend.jobs import create_job, create_job_from_lead, list_jobs as list_job_folders
+from canisend.pipeline import run_pipeline as run_job_pipeline
+from canisend.profile import init_profile as create_profile
+from canisend.rss import fetch_rss_text, filter_job_leads, parse_jobs_ac_uk_rss, write_job_leads
+from canisend.typst import render_typst_files
+from canisend.workspace import (
+    doctor_lines,
+    init_workspace as create_workspace,
+    load_workspace_config,
+    update_workspace_defaults,
+)
+
+app = typer.Typer(
+    help="Prepare evidence-backed academic and professional job application materials from local files.",
+    no_args_is_help=True,
+)
+
+
+@app.command("init-profile")
+def init_profile(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    profile_dir: Path | None = typer.Option(
+        None,
+        "--profile-dir",
+        help="Directory for profile evidence files. Relative paths are resolved against --workspace.",
+    ),
+    mode: str = typer.Option(
+        "hybrid",
+        "--mode",
+        help="Profile scaffold mode: markdown, typst, or hybrid.",
+    ),
+) -> None:
+    """Create starter profile files."""
+    config = load_workspace_config(workspace)
+    resolved_profile_dir = config.path("profile_dir", profile_dir)
+    try:
+        created = create_profile(resolved_profile_dir, mode=mode)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Profile ready at {resolved_profile_dir}")
+    if created:
+        typer.echo(f"Created {len(created)} profile files.")
+    else:
+        typer.echo("No files created; existing profile files were left unchanged.")
+
+
+@app.command("init-workspace")
+def init_workspace(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory for private profile, jobs, local prompts, and agent skills.",
+    ),
+    profile_mode: str = typer.Option(
+        "typst",
+        "--profile-mode",
+        help="Profile scaffold mode: markdown, typst, or hybrid.",
+    ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="Overwrite existing default resources and config files.",
+    ),
+) -> None:
+    """Create a productized user workspace without requiring a repository fork."""
+    try:
+        created = create_workspace(workspace, profile_mode=profile_mode, overwrite=overwrite)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Workspace ready at {workspace}")
+    if created:
+        typer.echo(f"Created or updated {len(created)} files.")
+    else:
+        typer.echo("No files changed; existing workspace files were left unchanged.")
+
+
+@app.command("update-workspace")
+def update_workspace(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory whose default resources should be refreshed.",
+    ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="Overwrite local default-resource copies. Leave off to preserve local edits.",
+    ),
+) -> None:
+    """Copy current packaged prompts, templates, schemas, and agent skills into a workspace."""
+    copied = update_workspace_defaults(workspace, overwrite=overwrite)
+    typer.echo(f"Workspace defaults checked at {workspace}")
+    if copied:
+        typer.echo(f"Created or updated {len(copied)} files.")
+    else:
+        typer.echo("No default files changed; existing local files were left unchanged.")
+
+
+@app.command("doctor")
+def doctor(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory to inspect.",
+    ),
+) -> None:
+    """Report local workspace, provider, and rendering readiness."""
+    for line in doctor_lines(workspace):
+        typer.echo(line)
+
+
+@app.command("run-example")
+def run_example(
+    workspace: Path = typer.Option(
+        Path("/tmp/canisend-example"),
+        "--workspace",
+        help="Directory where the packaged fake-data example workspace should be created.",
+    ),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        help="Replace an existing non-empty example workspace.",
+    ),
+) -> None:
+    """Run the packaged end-to-end fake-data workflow locally."""
+    try:
+        result = run_packaged_example(workspace, overwrite=overwrite)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    typer.echo(f"Example workflow complete at {result.workspace}")
+    typer.echo(f"Job: {result.job_dir.relative_to(result.workspace)}")
+    typer.echo(f"RSS leads: {result.leads_file.relative_to(result.workspace)}")
+    typer.echo("Key outputs:")
+    for output in [
+        "parsed_job.json",
+        "02_fit_report.md",
+        "03_cover_letter_draft.md",
+        "05_criteria_checklist.md",
+        "07_material_review_checklist.md",
+        "typst/cover_letter_content.json",
+        "typst/cover_letter.typ",
+        "typst/application_package_content.json",
+        "typst/application_package.typ",
+    ]:
+        typer.echo(f"  - {result.job_dir.relative_to(result.workspace) / output}")
+    typer.echo("Next: inspect the generated job folder, then try the same workflow with your private workspace.")
+
+
+@app.command("extract-profile-evidence")
+def extract_profile_evidence_command(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    profile_dir: Path | None = typer.Option(
+        None,
+        "--profile-dir",
+        help="Directory containing profile.yaml and Typst profile sources. Relative paths are resolved against --workspace.",
+    ),
+) -> None:
+    """Generate normalized evidence Markdown from local profile sources."""
+    config = load_workspace_config(workspace)
+    written = extract_profile_evidence(config.path("profile_dir", profile_dir))
+    typer.echo(f"Generated {len(written)} evidence files.")
+
+
+@app.command("new-job")
+def new_job(
+    title: str = typer.Option(..., "--title", help="Job title."),
+    institution: str = typer.Option(..., "--institution", help="Hiring institution."),
+    deadline: str = typer.Option("unknown", "--deadline", help="Application deadline."),
+    source_url: str = typer.Option("", "--source-url", help="Original job advert URL."),
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    jobs_dir: Path | None = typer.Option(
+        None,
+        "--jobs-dir",
+        help="Directory for job folders. Relative paths are resolved against --workspace.",
+    ),
+    advert_file: Path | None = typer.Option(
+        None,
+        "--advert-file",
+        help="Local .md or .txt job advert file to import.",
+    ),
+) -> None:
+    """Create a local job folder and advert file."""
+    config = load_workspace_config(workspace)
+    try:
+        job_dir = create_job(
+            jobs_dir=config.path("jobs_dir", jobs_dir),
+            title=title,
+            institution=institution,
+            deadline=deadline,
+            source_url=source_url,
+            advert_file=advert_file,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Created job at {job_dir}")
+
+
+@app.command("new-job-from-lead")
+def new_job_from_lead(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    leads_file: Path | None = typer.Option(
+        None,
+        "--leads-file",
+        help="Local RSS lead JSON file created by fetch-jobs-ac-uk. Relative paths are resolved against --workspace.",
+    ),
+    lead_index: int = typer.Option(..., "--lead-index", help="Zero-based index of the selected lead."),
+    institution: str = typer.Option(..., "--institution", help="Hiring institution for the job workspace."),
+    deadline: str = typer.Option("unknown", "--deadline", help="Application deadline."),
+    title: str | None = typer.Option(None, "--title", help="Override the RSS lead title."),
+    jobs_dir: Path | None = typer.Option(
+        None,
+        "--jobs-dir",
+        help="Directory for job folders. Relative paths are resolved against --workspace.",
+    ),
+) -> None:
+    """Create a local job folder from a selected RSS lead without scraping."""
+    config = load_workspace_config(workspace)
+    try:
+        job_dir = create_job_from_lead(
+            leads_file=config.lead_file(leads_file),
+            lead_index=lead_index,
+            jobs_dir=config.path("jobs_dir", jobs_dir),
+            institution=institution,
+            deadline=deadline,
+            title=title,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Created job from lead at {job_dir}")
+
+
+@app.command("list-jobs")
+def list_jobs_command(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    jobs_dir: Path | None = typer.Option(
+        None,
+        "--jobs-dir",
+        help="Directory containing job folders. Relative paths are resolved against --workspace.",
+    ),
+) -> None:
+    """List all job folders with status, deadline, and institution."""
+    config = load_workspace_config(workspace)
+    jobs = list_job_folders(config.path("jobs_dir", jobs_dir))
+    if not jobs:
+        typer.echo("No job folders found.")
+        return
+    typer.echo(f"{'Deadline':<12} {'Status':<18} {'Institution':<30} {'Title'}")
+    typer.echo("-" * 90)
+    for job in jobs:
+        typer.echo(f"{job['deadline']:<12} {job['status']:<18} {job['institution'][:28]:<30} {job['title'][:40]}")
+    typer.echo(f"\n{len(jobs)} job(s) found.")
+
+
+@app.command("fetch-jobs-ac-uk")
+def fetch_jobs_ac_uk(
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    feed_url: str = typer.Option("", "--feed-url", help="jobs.ac.uk RSS feed URL."),
+    rss_file: Path | None = typer.Option(
+        None,
+        "--rss-file",
+        help="Local RSS XML file for testing or offline import.",
+    ),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        help="JSON output path. Relative paths are resolved against --workspace.",
+    ),
+    include: list[str] = typer.Option([], "--include", help="Include jobs matching this keyword."),
+    exclude: list[str] = typer.Option([], "--exclude", help="Exclude jobs matching this keyword."),
+    limit: int = typer.Option(100, "--limit", help="Maximum number of leads to write."),
+) -> None:
+    """Fetch jobs.ac.uk RSS leads and apply local keyword filters."""
+    if rss_file is None and not feed_url:
+        raise typer.BadParameter("Provide --feed-url or --rss-file.")
+
+    config = load_workspace_config(workspace)
+    output_path = config.lead_file(output)
+    xml_text = rss_file.read_text(encoding="utf-8") if rss_file is not None else fetch_rss_text(feed_url)
+    leads = parse_jobs_ac_uk_rss(xml_text, feed_url=feed_url)
+    filtered = filter_job_leads(leads, include_keywords=include, exclude_keywords=exclude)
+    limited = filtered[:limit]
+    write_job_leads(output_path, limited)
+    typer.echo(f"Wrote {len(limited)} jobs.ac.uk leads to {output_path}")
+
+
+@app.command("run")
+def run_pipeline(
+    job: Path = typer.Option(..., "--job", help="Path to the job folder."),
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    profile_dir: Path | None = typer.Option(
+        None,
+        "--profile-dir",
+        help="Directory containing generated profile evidence. Relative paths are resolved against --workspace.",
+    ),
+    llm_parser: bool = typer.Option(
+        False,
+        "--llm-parser",
+        help="Use configured LLM provider and prompts/job_parser.md instead of deterministic parsing.",
+    ),
+    llm_drafts: bool = typer.Option(
+        False,
+        "--llm-drafts",
+        help="Use configured LLM provider for fit report, cover letter, CV notes, and criteria checklist.",
+    ),
+    prompt_dir: Path | None = typer.Option(
+        None,
+        "--prompt-dir",
+        help="Directory containing application prompt files. Relative paths are resolved against --workspace.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview what would be generated without writing any files.",
+    ),
+) -> None:
+    """Run the application preparation pipeline for one job."""
+    config = load_workspace_config(workspace)
+    job_dir = config.job_dir(job)
+    if dry_run:
+        from canisend.evidence import load_generated_evidence
+        from canisend.llm import load_llm_config, provider_from_config
+        from canisend.parse import parse_job_advert, parse_job_advert_with_provider
+        from canisend.resource_files import read_resource_text
+
+        import yaml as _yaml
+
+        metadata = _yaml.safe_load((job_dir / "job.yaml").read_text(encoding="utf-8"))
+        advert_text = (job_dir / "job_advert.md").read_text(encoding="utf-8")
+        evidence = load_generated_evidence(config.path("profile_dir", profile_dir))
+        if llm_parser:
+            prompt_text = read_resource_text("prompts/job_parser.md", local_path=config.path("prompt_dir", prompt_dir) / "job_parser.md")
+            provider = provider_from_config(load_llm_config())
+            parsed_job = parse_job_advert_with_provider(advert_text=advert_text, metadata=metadata, provider=provider, prompt_text=prompt_text)
+            typer.echo("Parser: LLM-backed")
+        else:
+            parsed_job = parse_job_advert(advert_text, metadata)
+            typer.echo("Parser: deterministic")
+
+        typer.echo(f"  Title: {parsed_job['title']}")
+        typer.echo(f"  Institution: {parsed_job['institution']}")
+        typer.echo(f"  Essential criteria: {len(parsed_job['essential_criteria'])}")
+        typer.echo(f"  Desirable criteria: {len(parsed_job['desirable_criteria'])}")
+        typer.echo(f"  Required documents: {len(parsed_job['required_documents'])}")
+        typer.echo(f"  Evidence items available: {len(evidence)}")
+        typer.echo(f"\nOutputs that would be generated:")
+
+        outputs = [
+            "parsed_job.json", "01_job_summary.md", "02_fit_report.md",
+            "03_cover_letter_draft.md", "04_cv_tailoring_notes.md",
+            "05_criteria_checklist.md", "06_final_application_package.md",
+            "07_material_review_checklist.md",
+            "typst/cover_letter_content.json", "typst/cover_letter.typ",
+            "typst/application_package_content.json", "typst/application_package.typ",
+        ]
+        for output in outputs:
+            typer.echo(f"  - {job_dir}/{output}")
+        typer.echo(f"\nDraft mode: {'LLM-backed' if llm_drafts else 'deterministic'}")
+        return
+
+    written = run_job_pipeline(
+        job_dir,
+        profile_dir=config.path("profile_dir", profile_dir),
+        use_llm_parser=llm_parser,
+        use_llm_drafts=llm_drafts,
+        prompt_dir=config.path("prompt_dir", prompt_dir),
+    )
+    typer.echo(f"Generated {len(written)} files for {job_dir}")
+
+
+@app.command("render-typst")
+def render_typst(
+    job: Path = typer.Option(..., "--job", help="Path to the job folder."),
+    workspace: Path = typer.Option(
+        Path("."),
+        "--workspace",
+        help="User workspace directory containing canisend.yaml.",
+    ),
+    typst_bin: str = typer.Option("typst", "--typst-bin", help="Typst executable path or command name."),
+) -> None:
+    """Render generated Typst files for one job."""
+    config = load_workspace_config(workspace)
+    job_dir = config.job_dir(job)
+    try:
+        rendered = render_typst_files(job_dir, typst_bin=typst_bin)
+    except FileNotFoundError as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1) from exc
+    except RuntimeError as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Rendered {len(rendered)} PDF files for {job_dir}")

canisend/config_schema.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+VALID_CONFIG_KEYS = {
+    "profile_dir",
+    "jobs_dir",
+    "job_leads_dir",
+    "prompt_dir",
+    "template_dir",
+    "schema_dir",
+    "agent_skills_dir",
+}
+
+
+def validate_workspace_config(config_path: Path) -> list[str]:
+    if not config_path.exists():
+        return ["canisend.yaml not found. Run `canisend init-workspace` to create it."]
+
+    try:
+        data = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        return [f"canisend.yaml is not valid YAML: {exc}"]
+
+    if not isinstance(data, dict):
+        return ["canisend.yaml must contain a mapping of key-value pairs."]
+
+    warnings: list[str] = []
+    for key, value in data.items():
+        if key not in VALID_CONFIG_KEYS:
+            warnings.append(f"Unknown key in canisend.yaml: '{key}'. Valid keys: {', '.join(sorted(VALID_CONFIG_KEYS))}")
+        if not isinstance(value, (str, type(None))):
+            warnings.append(f"Value for '{key}' must be a string or null, got {type(value).__name__}.")
+
+    for key in VALID_CONFIG_KEYS:
+        if key not in data:
+            warnings.append(f"Missing key in canisend.yaml: '{key}'. Default will be used: '{_default_for(key)}'.")
+
+    return warnings
+
+
+def _default_for(key: str) -> str:
+    defaults: dict[str, str] = {
+        "profile_dir": "profile",
+        "jobs_dir": "jobs",
+        "job_leads_dir": "job_leads",
+        "prompt_dir": "prompts",
+        "template_dir": "templates",
+        "schema_dir": "schemas",
+        "agent_skills_dir": "agent-skills",
+    }
+    return defaults.get(key, "")