{"id":48462871,"url":"https://github.com/hypertrial/honestroles","last_synced_at":"2026-04-07T03:01:35.726Z","repository":{"id":338541300,"uuid":"1151878718","full_name":"hypertrial/honestroles","owner":"hypertrial","description":"Clean, filter, label, and rate job description data","archived":false,"fork":false,"pushed_at":"2026-03-08T10:17:03.000Z","size":570,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-08T13:57:28.602Z","etag":null,"topics":["data-science","jobs","jobsearch","python"],"latest_commit_sha":null,"homepage":"https://hypertrial.github.io/honestroles/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypertrial.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING_PLUGIN.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T02:50:53.000Z","updated_at":"2026-03-08T10:17:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hypertrial/honestroles","commit_stats":null,"previous_names":["hypertrial/honestroles"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/hypertrial/honestroles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertrial%2Fhonestroles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertrial%2Fhonestroles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertrial%2Fhonestroles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertrial%2Fhonestroles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypertrial","download_url":"https://codeload.github.com/hypertrial/honestroles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypertrial%2Fhonestroles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31498070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"online","status_checked_at":"2026-04-07T02:00:07.164Z","response_time":105,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","jobs","jobsearch","python"],"created_at":"2026-04-07T03:01:34.804Z","updated_at":"2026-04-07T03:01:35.719Z","avatar_url":"https://github.com/hypertrial.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HonestRoles\n\nHonestRoles is a deterministic, config-driven pipeline runtime for job data with Polars and explicit plugin manifests.\n\n## Start With the App\n\nUse the HonestRoles app first: [honestroles.com](https://honestroles.com).\n\n- Launch app: [https://honestroles.com](https://honestroles.com)\n- App guide: [App Quickstart](https://honestroles.com/docs/app/get-started/)\n\n## Choose Your Path\n\n- App users: start in the browser at [honestroles.com](https://honestroles.com)\n- Developers and integrators: use the CLI/SDK sections below\n\n## Install (Developer)\n\n```bash\n$ python -m venv .venv\n$ . .venv/bin/activate\n$ python -m pip install --upgrade pip\n$ pip install honestroles\n```\n\n## 5-Minute First Run (Developer)\n\nFrom the repository root:\n\n```bash\n$ python examples/create_sample_dataset.py\n$ honestroles run --pipeline-config examples/sample_pipeline.toml --plugins examples/sample_plugins.toml\n$ ls -lh examples/jobs_scored.parquet\n```\n\nExpected CLI diagnostics include `stage_rows`, `plugin_counts`, and `final_rows`.\n\n## CLI\n\n```bash\n$ honestroles ingest sync --source greenhouse --source-ref stripe --quality-policy ingest_quality.toml --strict-quality --merge-policy updated_hash --retain-snapshots 30 --prune-inactive-days 90 --format table\n$ honestroles ingest validate --source greenhouse --source-ref stripe --quality-policy ingest_quality.toml --strict-quality --format table\n$ honestroles ingest sync-all --manifest ingest.toml --format table\n$ honestroles recommend build-index --input-parquet dist/ingest/greenhouse/stripe/jobs.parquet --policy recommendation.toml --format table\n$ honestroles recommend match --index-dir dist/recommend/index/\u003cindex_id\u003e --candidate-json examples/candidate.json --top-k 25 --include-excluded --format table\n$ honestroles recommend evaluate --index-dir dist/recommend/index/\u003cindex_id\u003e --golden-set examples/recommend_golden_set.json --thresholds recommend_eval.toml --format table\n$ honestroles recommend feedback add --profile-id jane_doe --job-id 12345 --event interviewed --format table\n$ honestroles publish neondb migrate --database-url-env NEON_DATABASE_URL --schema honestroles_api --format table\n$ honestroles publish neondb sync --database-url-env NEON_DATABASE_URL --schema honestroles_api --jobs-parquet dist/ingest/greenhouse/stripe/jobs.parquet --index-dir dist/recommend/index/\u003cindex_id\u003e --sync-report dist/ingest/greenhouse/stripe/sync_report.json --require-quality-pass --format table\n$ honestroles publish neondb verify --database-url-env NEON_DATABASE_URL --schema honestroles_api --format table\n$ honestroles init --input-parquet data/jobs.parquet --pipeline-config pipeline.toml --plugins-manifest plugins.toml\n$ honestroles doctor --pipeline-config pipeline.toml --plugins plugins.toml --format table\n$ honestroles reliability check --pipeline-config pipeline.toml --plugins plugins.toml --strict --format table\n$ honestroles run --pipeline-config pipeline.toml --plugins plugins.toml\n$ honestroles plugins validate --manifest plugins.toml\n$ honestroles config validate --pipeline pipeline.toml\n$ honestroles report-quality --pipeline-config pipeline.toml\n$ honestroles runs list --limit 10 --command ingest.sync --format table\n$ honestroles scaffold-plugin --name my-plugin --output-dir .\n```\n\n## Python API\n\n```python\nfrom honestroles import (\n    HonestRolesRuntime,\n    build_retrieval_index,\n    evaluate_relevance,\n    migrate_neondb,\n    match_jobs,\n    publish_neondb_sync,\n    record_feedback_event,\n    sync_source,\n    sync_sources_from_manifest,\n    summarize_feedback,\n    validate_ingestion_source,\n    verify_neondb_contract,\n)\n\ningest = sync_source(\n    source=\"greenhouse\",\n    source_ref=\"stripe\",\n    quality_policy_file=\"ingest_quality.toml\",\n    strict_quality=False,\n    merge_policy=\"updated_hash\",\n    retain_snapshots=30,\n    prune_inactive_days=90,\n)\nprint(ingest.rows_written, ingest.output_parquet)\n\nvalidation = validate_ingestion_source(\n    source=\"greenhouse\",\n    source_ref=\"stripe\",\n    quality_policy_file=\"ingest_quality.toml\",\n    strict_quality=True,\n)\nprint(validation.report.status, validation.rows_evaluated)\n\nbatch = sync_sources_from_manifest(manifest_path=\"ingest.toml\")\nprint(batch.status, batch.total_sources, batch.fail_count)\n\nindex = build_retrieval_index(\n    input_parquet=\"dist/ingest/greenhouse/stripe/jobs.parquet\",\n    policy_file=\"recommendation.toml\",\n)\nmatches = match_jobs(\n    index_dir=index.index_dir,\n    candidate_json=\"examples/candidate.json\",\n    top_k=25,\n    include_excluded=True,\n)\nprint(matches.status, len(matches.results))\n\nevaluation = evaluate_relevance(\n    index_dir=index.index_dir,\n    golden_set=\"examples/recommend_golden_set.json\",\n    thresholds_file=\"recommend_eval.toml\",\n)\nprint(evaluation.status, evaluation.metrics)\n\nrecord_feedback_event(profile_id=\"jane_doe\", job_id=\"12345\", event=\"interviewed\")\nprint(summarize_feedback(profile_id=\"jane_doe\").weights)\n\nprint(migrate_neondb(database_url_env=\"NEON_DATABASE_URL\").status)\npublish_result = publish_neondb_sync(\n    database_url_env=\"NEON_DATABASE_URL\",\n    jobs_parquet=\"dist/ingest/greenhouse/stripe/jobs.parquet\",\n    index_dir=index.index_dir,\n    sync_report=\"dist/ingest/greenhouse/stripe/sync_report.json\",\n)\nprint(publish_result.batch_id, verify_neondb_contract(database_url_env=\"NEON_DATABASE_URL\").status)\n\nruntime = HonestRolesRuntime.from_configs(\n    pipeline_config_path=\"pipeline.toml\",\n    plugin_manifest_path=\"plugins.toml\",\n)\nresult = runtime.run()\n\nprint(result.diagnostics)\nprint(result.dataset.to_polars().head())\nprint(result.application_plan[:3])\n```\n\n## Documentation\n\n- App home: https://honestroles.com\n- Docs home: https://honestroles.com/docs/\n- Local docs source: `docs/`\n- Start here in docs: `docs/index.md`\n\n## Development\n\n```bash\n$ pip install -e \".[dev,docs]\"\n$ pytest -q\n$ pytest tests/docs -q\n$ bash scripts/check_docs_refs.sh\n# Optional live connector smoke (requires refs):\n# HONESTROLES_SMOKE_GREENHOUSE_REF, HONESTROLES_SMOKE_LEVER_REF,\n# HONESTROLES_SMOKE_ASHBY_REF, HONESTROLES_SMOKE_WORKABLE_REF\n$ bash scripts/run_ingest_smoke.sh\n# Optional Neon DB smoke (requires NEON_DATABASE_URL):\n$ PYTHON_BIN=.venv/bin/python DATABASE_URL_ENV=NEON_DATABASE_URL SCHEMA=honestroles_api bash scripts/run_neondb_smoke.sh\n```\n\nFor local profiling data, keep large parquet inputs under `data/` and write generated artifacts under `dist/` (both are ignored by git).\n\n## Maintainer Notes\n\n- PyPI publishing is manual and token-based via `bash scripts/publish_pypi.sh`.\n- The script reads `PYPI_API_KEY` (or `PYPI_API_TOKEN`) from env/`.env`.\n- The GitHub `Release` workflow is manual (`workflow_dispatch`) only.\n- Before publish, run deterministic gate:\n\n```bash\n$ PYTHON_BIN=.venv/bin/python bash scripts/run_coverage.sh\n```\n\n- Full maintainer runbook: `docs/for-maintainers/release-and-pypi.md`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypertrial%2Fhonestroles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypertrial%2Fhonestroles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypertrial%2Fhonestroles/lists"}