openrecruiter 0.1.0__tar.gz

openrecruiter-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+
+# Node
+node_modules/
+product/frontend/dist/
+product/electron/dist/
+
+# Database
+*.db
+*.sqlite
+chroma_data/
+
+# Environment
+.env
+
+# IDE
+.vscode/
+.idea/
+
+# Cache
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Credentials
+credentials.json
+token.json
+
+# Uploads (resumes)
+product/backend/uploads/
+
+# Build artifacts
+*.tsbuildinfo
+
+# Electron build
+release/
+product/release/
+
+# Python package builds
+dist/

openrecruiter-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: openrecruiter
+Version: 0.1.0
+Summary: The recruiting engine behind Open Recruiter — parse, retrieve, rank, and an agent over tools.
+License: MIT
+Keywords: agent,ats,candidate-search,llm,ranking,recruiting
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=0.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: litellm>=1.60
+Requires-Dist: pydantic>=2.10
+Description-Content-Type: text/markdown
+
+# openrecruiter
+
+The recruiting engine behind [Open Recruiter](https://github.com/miao4ai/open_recruiter):
+parse resumes and job descriptions, retrieve and rank candidates, draft outreach, and run an
+agent that does all of it through tools.
+
+The desktop app is a consumer of this package, so everything shipped here is exercised by a
+real application rather than only by its own tests.
+
+## Install
+
+Straight from the repository:
+
+```bash
+pip install "git+https://github.com/miao4ai/open_recruiter.git#subdirectory=sdk/core"
+```
+
+Or a released wheel, from the [Releases](https://github.com/miao4ai/open_recruiter/releases)
+page:
+
+```bash
+pip install https://github.com/miao4ai/open_recruiter/releases/download/sdk-core-v0.1.0/openrecruiter-0.1.0-py3-none-any.whl
+```
+
+> Not on PyPI yet, so plain `pip install openrecruiter` will not find it. GitHub Packages has
+> no Python registry, which is why the wheel is attached to a Release rather than appearing in
+> the repository's Packages panel.
+
+No local model is downloaded, at import or at runtime. Embeddings are an API call and chat is
+a hosted provider, so it runs on CPU, on macOS, and in a container with no GPU — 97 packages
+installed, none of them a training stack.
+
+## Quick start
+
+```python
+from openrecruiter import Recruiter
+
+r = Recruiter(anthropic_api_key="sk-ant-...", voyage_api_key="pa-...")
+
+job = r.add_job(open("jd.txt").read())          # parsed into title, skills, requirements
+r.add_candidate(open("resume.txt").read())      # parsed into a structured profile
+
+for match in r.rank(job.id, top_k=10):
+    print(f"{match.score:.2f}  {match.candidate_id}  {match.reasoning}")
+```
+
+Without a Voyage key, retrieval is disabled and ranking falls back to the LLM — the package
+still works, it just reads every candidate instead of shortlisting first.
+
+## The agent
+
+The model is given real tools and decides what to call and when it is done, so one request
+can span several steps: rank a job, read the result, then draft the emails.
+
+```python
+for event in r.chat("who are the three strongest fits for the CUDA role, and draft an intro to each"):
+    match event:
+        case TextDelta():        print(event.text, end="", flush=True)
+        case ToolCall():         print(f"\n[{event.name}]")
+        case ApprovalRequired(): ...   # a gated tool is waiting for a human
+```
+
+Events are `TextDelta`, `ToolCall`, `ToolResult`, `ApprovalRequired`, and `Finished`. Text
+streams as it is generated; tool calls are only emitted once their arguments are complete.
+
+For a one-liner, `r.ask("...")` returns just the final text.
+
+### Approval gates
+
+A tool marked `requires_approval` stops the run rather than acting. Anything the model
+queued behind it is held too, so the gate cannot be stepped around:
+
+```python
+events = list(r.chat("email the top candidate"))
+if agent.pending:                                   # serialisable — store it, decide later
+    list(agent.resume(agent.pending, approved=True))
+```
+
+### Your own tools
+
+```python
+from openrecruiter import Tool
+
+check_calendar = Tool(
+    name="check_calendar",
+    description="Look at the recruiter's availability this week",
+    parameters={"type": "object", "properties": {"days": {"type": "integer"}}},
+    fn=lambda days=7: my_calendar.free_slots(days),
+)
+
+r = Recruiter(anthropic_api_key="...", extra_tools=[check_calendar])
+```
+
+## Ranking
+
+Ranking is the main extension point. One interface, several backends:
+
+```
+Ranker
+├── EmbeddingRanker   vector similarity — the default, cheap enough for the whole pool
+├── APIRanker         an LLM scores each candidate and explains itself
+├── TwoStageRanker    retrieve with one, rerank the shortlist with the other
+└── your own          implement rank(job, candidates, top_k) and pass it in
+```
+
+`TwoStageRanker` is the shape the ranking research targets — the first stage optimises
+recall, the second optimises relevance over a few hundred candidates:
+
+```python
+from openrecruiter import APIRanker, EmbeddingRanker, TwoStageRanker
+
+r.ranker = TwoStageRanker(
+    EmbeddingRanker(r.index),
+    APIRanker(r.llm),
+    shortlist=200,
+)
+```
+
+Backends that need a local model live in their own distributions — `recruitgpt` for the
+distilled ranker, `openrecruiter-fairness` for bias-aware reranking — so nothing heavy
+reaches this install. Both must lazy-load: no download until a user selects that backend.
+
+## Bringing your own storage
+
+`Store` and `VectorIndex` are protocols. Implement them over a database you already have and
+nothing above the storage layer changes — that is how the desktop app keeps its existing
+schema while running on this package.
+
+```python
+class MyStore:
+    def add_job(self, job): ...
+    def get_job(self, job_id): ...
+    def list_jobs(self, limit=100): ...
+    # ... six more, all in openrecruiter.store.base
+
+r = Recruiter(config, store=MyStore())
+```
+
+The default `SQLiteStore` is a working reference in four tables.
+
+## Development
+
+```bash
+cd sdk/core
+uv sync
+uv run pytest              # no network calls: the LLM is faked end to end
+uv build --out-dir dist
+```
+
+Releasing: bump `version` in `pyproject.toml`, then push a matching tag.
+
+```bash
+git tag sdk-core-v0.1.1 && git push origin sdk-core-v0.1.1
+```
+
+CI checks the tag against the version, runs the tests, builds, installs the wheel in a clean
+environment and imports it, verifies no training stack came along, and attaches the artifacts
+to a Release.
+
+## License
+
+MIT

openrecruiter-0.1.0/README.md

@@ -0,0 +1,162 @@
+# openrecruiter
+
+The recruiting engine behind [Open Recruiter](https://github.com/miao4ai/open_recruiter):
+parse resumes and job descriptions, retrieve and rank candidates, draft outreach, and run an
+agent that does all of it through tools.
+
+The desktop app is a consumer of this package, so everything shipped here is exercised by a
+real application rather than only by its own tests.
+
+## Install
+
+Straight from the repository:
+
+```bash
+pip install "git+https://github.com/miao4ai/open_recruiter.git#subdirectory=sdk/core"
+```
+
+Or a released wheel, from the [Releases](https://github.com/miao4ai/open_recruiter/releases)
+page:
+
+```bash
+pip install https://github.com/miao4ai/open_recruiter/releases/download/sdk-core-v0.1.0/openrecruiter-0.1.0-py3-none-any.whl
+```
+
+> Not on PyPI yet, so plain `pip install openrecruiter` will not find it. GitHub Packages has
+> no Python registry, which is why the wheel is attached to a Release rather than appearing in
+> the repository's Packages panel.
+
+No local model is downloaded, at import or at runtime. Embeddings are an API call and chat is
+a hosted provider, so it runs on CPU, on macOS, and in a container with no GPU — 97 packages
+installed, none of them a training stack.
+
+## Quick start
+
+```python
+from openrecruiter import Recruiter
+
+r = Recruiter(anthropic_api_key="sk-ant-...", voyage_api_key="pa-...")
+
+job = r.add_job(open("jd.txt").read())          # parsed into title, skills, requirements
+r.add_candidate(open("resume.txt").read())      # parsed into a structured profile
+
+for match in r.rank(job.id, top_k=10):
+    print(f"{match.score:.2f}  {match.candidate_id}  {match.reasoning}")
+```
+
+Without a Voyage key, retrieval is disabled and ranking falls back to the LLM — the package
+still works, it just reads every candidate instead of shortlisting first.
+
+## The agent
+
+The model is given real tools and decides what to call and when it is done, so one request
+can span several steps: rank a job, read the result, then draft the emails.
+
+```python
+for event in r.chat("who are the three strongest fits for the CUDA role, and draft an intro to each"):
+    match event:
+        case TextDelta():        print(event.text, end="", flush=True)
+        case ToolCall():         print(f"\n[{event.name}]")
+        case ApprovalRequired(): ...   # a gated tool is waiting for a human
+```
+
+Events are `TextDelta`, `ToolCall`, `ToolResult`, `ApprovalRequired`, and `Finished`. Text
+streams as it is generated; tool calls are only emitted once their arguments are complete.
+
+For a one-liner, `r.ask("...")` returns just the final text.
+
+### Approval gates
+
+A tool marked `requires_approval` stops the run rather than acting. Anything the model
+queued behind it is held too, so the gate cannot be stepped around:
+
+```python
+events = list(r.chat("email the top candidate"))
+if agent.pending:                                   # serialisable — store it, decide later
+    list(agent.resume(agent.pending, approved=True))
+```
+
+### Your own tools
+
+```python
+from openrecruiter import Tool
+
+check_calendar = Tool(
+    name="check_calendar",
+    description="Look at the recruiter's availability this week",
+    parameters={"type": "object", "properties": {"days": {"type": "integer"}}},
+    fn=lambda days=7: my_calendar.free_slots(days),
+)
+
+r = Recruiter(anthropic_api_key="...", extra_tools=[check_calendar])
+```
+
+## Ranking
+
+Ranking is the main extension point. One interface, several backends:
+
+```
+Ranker
+├── EmbeddingRanker   vector similarity — the default, cheap enough for the whole pool
+├── APIRanker         an LLM scores each candidate and explains itself
+├── TwoStageRanker    retrieve with one, rerank the shortlist with the other
+└── your own          implement rank(job, candidates, top_k) and pass it in
+```
+
+`TwoStageRanker` is the shape the ranking research targets — the first stage optimises
+recall, the second optimises relevance over a few hundred candidates:
+
+```python
+from openrecruiter import APIRanker, EmbeddingRanker, TwoStageRanker
+
+r.ranker = TwoStageRanker(
+    EmbeddingRanker(r.index),
+    APIRanker(r.llm),
+    shortlist=200,
+)
+```
+
+Backends that need a local model live in their own distributions — `recruitgpt` for the
+distilled ranker, `openrecruiter-fairness` for bias-aware reranking — so nothing heavy
+reaches this install. Both must lazy-load: no download until a user selects that backend.
+
+## Bringing your own storage
+
+`Store` and `VectorIndex` are protocols. Implement them over a database you already have and
+nothing above the storage layer changes — that is how the desktop app keeps its existing
+schema while running on this package.
+
+```python
+class MyStore:
+    def add_job(self, job): ...
+    def get_job(self, job_id): ...
+    def list_jobs(self, limit=100): ...
+    # ... six more, all in openrecruiter.store.base
+
+r = Recruiter(config, store=MyStore())
+```
+
+The default `SQLiteStore` is a working reference in four tables.
+
+## Development
+
+```bash
+cd sdk/core
+uv sync
+uv run pytest              # no network calls: the LLM is faked end to end
+uv build --out-dir dist
+```
+
+Releasing: bump `version` in `pyproject.toml`, then push a matching tag.
+
+```bash
+git tag sdk-core-v0.1.1 && git push origin sdk-core-v0.1.1
+```
+
+CI checks the tag against the version, runs the tests, builds, installs the wheel in a clean
+environment and imports it, verifies no training stack came along, and attaches the artifacts
+to a Release.
+
+## License
+
+MIT

openrecruiter-0.1.0/openrecruiter/__init__.py

@@ -0,0 +1,72 @@
+"""Open Recruiter — the recruiting engine behind the Open Recruiter app.
+
+Parse resumes and job descriptions, retrieve and rank candidates, draft
+outreach, and run an agent that does all of it through tools.
+
+    from openrecruiter import Recruiter
+
+    r = Recruiter(anthropic_api_key="sk-ant-...")
+    job = r.add_job(jd_text)
+    matches = r.rank(job.id, top_k=10)
+
+No local model is downloaded, at import or at runtime. Embeddings are an API
+call and chat is a hosted provider, so the package runs on CPU, on macOS, and in
+a container without a GPU.
+"""
+
+from openrecruiter.agent import Agent, PendingApproval
+from openrecruiter.client import Recruiter
+from openrecruiter.config import Config
+from openrecruiter.context import build_pipeline_context
+from openrecruiter.events import (
+    ApprovalRequired,
+    Event,
+    Finished,
+    TextDelta,
+    ToolCall,
+    ToolResult,
+)
+from openrecruiter.ranking import APIRanker, EmbeddingRanker, Ranker, TwoStageRanker
+from openrecruiter.store import (
+    ChromaVectorIndex,
+    NullVectorIndex,
+    SQLiteStore,
+    Store,
+    VectorIndex,
+)
+from openrecruiter.tools import Tool, ToolRegistry, tool
+from openrecruiter.types import Candidate, CandidateStatus, EmailDraft, Job, Match
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APIRanker",
+    "Agent",
+    "ApprovalRequired",
+    "build_pipeline_context",
+    "Candidate",
+    "CandidateStatus",
+    "ChromaVectorIndex",
+    "Config",
+    "EmailDraft",
+    "EmbeddingRanker",
+    "Event",
+    "Finished",
+    "Job",
+    "Match",
+    "NullVectorIndex",
+    "PendingApproval",
+    "Ranker",
+    "Recruiter",
+    "SQLiteStore",
+    "Store",
+    "TextDelta",
+    "Tool",
+    "ToolCall",
+    "ToolRegistry",
+    "ToolResult",
+    "TwoStageRanker",
+    "VectorIndex",
+    "__version__",
+    "tool",
+]

openrecruiter-0.1.0/openrecruiter/agent.py

@@ -0,0 +1,237 @@
+"""The agent loop.
+
+The model is given real tools and decides for itself what to call, in what
+order, and when it is finished. That is the whole difference from asking a model
+to emit an action name and dispatching it: a single request can retrieve a job,
+rank the pool, read the top result, and draft three emails, because each tool
+result feeds the next decision.
+
+The loop is a generator of `Event`s so a caller can render text as it arrives
+rather than after the whole turn completes, and so it can stop at an approval
+gate without the agent needing to know what a user interface is.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterator
+
+from pydantic import BaseModel, Field
+
+from openrecruiter.events import (
+    ApprovalRequired,
+    Event,
+    Finished,
+    TextDelta,
+    ToolCall,
+    ToolResult,
+)
+from openrecruiter.prompts import AGENT_SYSTEM
+from openrecruiter.providers.llm import LLM, LLMError
+from openrecruiter.tools.base import ToolError, ToolRegistry
+
+log = logging.getLogger(__name__)
+
+DEFAULT_MAX_STEPS = 8
+
+
+class PendingApproval(BaseModel):
+    """Everything needed to carry on once a human has decided.
+
+    A plain model rather than a closure, because the decision usually arrives on
+    a later HTTP request in a different process. Store it, then hand it back to
+    `resume()`.
+    """
+
+    messages: list[dict] = Field(default_factory=list)
+    tool_name: str = ""
+    tool_call_id: str = ""
+    arguments: dict = Field(default_factory=dict)
+    #: Calls the model made in the same turn that have not run yet.
+    queued: list[dict] = Field(default_factory=list)
+    step: int = 0
+
+
+class Agent:
+    """Runs a conversation with tools until the work is done."""
+
+    def __init__(
+        self,
+        llm: LLM,
+        tools: ToolRegistry,
+        system: str = AGENT_SYSTEM,
+        max_steps: int = DEFAULT_MAX_STEPS,
+    ) -> None:
+        self.llm = llm
+        self.tools = tools
+        self.system = system
+        self.max_steps = max_steps
+        #: Set when a run stops at an approval gate; None otherwise.
+        self.pending: PendingApproval | None = None
+
+    # ── entry points ─────────────────────────────────────────────────────
+
+    def run(self, message: str, history: list[dict] | None = None) -> Iterator[Event]:
+        """Answer `message`, calling tools as needed."""
+        messages = [*(history or []), {"role": "user", "content": message}]
+        self.pending = None
+        yield from self._loop(messages, step=0)
+
+    def resume(self, pending: PendingApproval, approved: bool) -> Iterator[Event]:
+        """Continue a run that stopped for approval.
+
+        Declining is not an error: the model is told the user refused and gets to
+        respond to that, which is usually more useful than an abandoned turn.
+        """
+        self.pending = None
+        messages = list(pending.messages)
+
+        if approved:
+            result = self._invoke(pending.tool_name, pending.arguments)
+            yield result
+            messages.append(_tool_message(pending.tool_call_id, result))
+        else:
+            declined = ToolResult(
+                id=pending.tool_call_id,
+                name=pending.tool_name,
+                error="The user declined this action. It was not performed.",
+            )
+            yield declined
+            messages.append(_tool_message(pending.tool_call_id, declined))
+
+        queued = [ToolCall(**c) for c in pending.queued]
+        stopped = yield from self._run_tools(queued, messages, pending.step)
+        if stopped:
+            return
+        yield from self._loop(messages, step=pending.step + 1)
+
+    # ── the loop ─────────────────────────────────────────────────────────
+
+    def _loop(self, messages: list[dict], step: int) -> Iterator[Event]:
+        schemas = self.tools.schemas()
+
+        while step < self.max_steps:
+            text_parts: list[str] = []
+            calls: list[ToolCall] = []
+
+            try:
+                for event in self.llm.stream(self.system, messages, tools=schemas):
+                    if isinstance(event, TextDelta):
+                        text_parts.append(event.text)
+                        yield event
+                    else:
+                        calls.append(event)
+            except LLMError as exc:
+                log.error("Agent step %d failed: %s", step, exc)
+                yield Finished(text="".join(text_parts), stop_reason="error", steps=step, error=str(exc))
+                return
+
+            text = "".join(text_parts)
+
+            if not calls:
+                yield Finished(text=text, stop_reason="end_turn", steps=step)
+                return
+
+            messages.append(_assistant_message(text, calls))
+
+            stopped = yield from self._run_tools(calls, messages, step)
+            if stopped:
+                return
+            step += 1
+
+        yield Finished(stop_reason="max_steps", steps=step)
+
+    def _run_tools(
+        self, calls: list[ToolCall], messages: list[dict], step: int
+    ) -> Iterator[Event]:
+        """Run each call in order. Returns True if the run stopped for approval.
+
+        Anything queued behind an approval gate is carried into `PendingApproval`
+        rather than run — the user has not agreed to those either, and running
+        them would make the gate cosmetic.
+        """
+        for i, call in enumerate(calls):
+            if self._needs_approval(call.name):
+                self.pending = PendingApproval(
+                    messages=messages,
+                    tool_name=call.name,
+                    tool_call_id=call.id,
+                    arguments=call.arguments,
+                    queued=[
+                        {"id": c.id, "name": c.name, "arguments": c.arguments}
+                        for c in calls[i + 1 :]
+                    ],
+                    step=step,
+                )
+                yield ApprovalRequired(
+                    id=call.id,
+                    name=call.name,
+                    arguments=call.arguments,
+                    description=self.tools.get(call.name).description,
+                )
+                yield Finished(stop_reason="awaiting_approval", steps=step)
+                return True
+
+            # Announced before it runs, so a caller can show what is happening
+            # rather than a spinner — a rank over a large pool is not instant.
+            yield call
+
+            result = self._invoke(call.name, call.arguments, call_id=call.id)
+            yield result
+            messages.append(_tool_message(call.id, result))
+
+        return False
+
+    # ── helpers ──────────────────────────────────────────────────────────
+
+    def _needs_approval(self, name: str) -> bool:
+        try:
+            return self.tools.get(name).requires_approval
+        except ToolError:
+            return False
+
+    def _invoke(self, name: str, arguments: dict, call_id: str = "") -> ToolResult:
+        """Call a tool, turning any failure into a result the model can read.
+
+        A tool raising must not end the turn: the model can often recover — fix
+        an argument, try a different tool — if it is told what went wrong.
+        """
+        try:
+            value = self.tools.call(name, arguments)
+        except ToolError as exc:
+            return ToolResult(id=call_id, name=name, error=str(exc))
+        except Exception as exc:  # noqa: BLE001 - tools are arbitrary user code
+            log.exception("Tool %s raised", name)
+            return ToolResult(id=call_id, name=name, error=f"{type(exc).__name__}: {exc}")
+        return ToolResult(id=call_id, name=name, result=value)
+
+
+# ── provider message shapes ──────────────────────────────────────────────
+
+
+def _assistant_message(text: str, calls: list[ToolCall]) -> dict:
+    return {
+        "role": "assistant",
+        "content": text or None,
+        "tool_calls": [
+            {
+                "id": c.id,
+                "type": "function",
+                "function": {"name": c.name, "arguments": json.dumps(c.arguments)},
+            }
+            for c in calls
+        ],
+    }
+
+
+def _tool_message(call_id: str, result: ToolResult) -> dict:
+    payload = {"error": result.error} if result.error else {"result": result.result}
+    return {
+        "role": "tool",
+        "tool_call_id": call_id,
+        "content": json.dumps(payload, default=str),
+    }
+
+
+__all__ = ["Agent", "PendingApproval", "DEFAULT_MAX_STEPS"]