# sentient-engineering/jobber architecture

> Architecture diagram of the GitHub repository sentient-engineering/jobber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sentient-engineering/jobber
- Repository: https://github.com/sentient-engineering/jobber

## Overview

##### Project type and purpose
- Project type: A command-line AI agent framework in Python, with two implementations (“jobber” and “jobber_fsm”) that autonomously navigate the web and apply to jobs on behalf of the user.
- Purpose: Accept user tasks and preferences, plan a sequence of browser interactions, execute them via Playwright, extract or enter data, and iterate until the task (e.g., applying for a job) is complete.

##### File structure
Top-level:
- pyproject.toml, requirements.txt – dependency declarations
- .env.example – environment variables (OpenAI key, LangSmith key)
- README.md – project overview
- jobber/ and jobber_fsm/ – two parallel agent implementations
- test/ – end-to-end and unit tests
“jobber” and “jobber_fsm” packages both contain:
- __main__.py – CLI entrypoint
- config.py or config/ – config loading
- core/
– agents/ (planner_agent, browser_nav_agent)
– orchestrator (system_orchestrator or fsm/orchestrator)
– memory/ (LTM)
– prompts/ (prompt templates)
– skills/ (atomic browser interactions: click, open_url, screenshot, etc.)
– playwright_manager or web_driver/playwright – abstraction over Playwright
- user_preferences/user_preferences.txt – resume path, job filters
- utils/ – CLI helpers, DOM helpers, logger, Pydantic models, extraction utilities

##### README for additional insights
- Two implementations: “vanilla” conversational orchestrator vs. FSM-based orchestrator
- Dependencies on:
– OpenAI API (chat models)
– Playwright for browser control
– Optional LangSmith for tracing
- Setup steps emphasize:
– Launching Chrome in remote-debugging mode
– Providing .env keys
– Customizing user_preferences.txt
– Running via “python -m jobber” or “python -m jobber_fsm”

a. Main components
1. CLI / Entrypoint
2. Configuration loader (.env, config.py)
3. Orchestrator
– jobber: SystemOrchestrator
– jobber_fsm: FSMOrchestrator
4. Agents
– PlannerAgent (generates high-level plan via OpenAI)
– BrowserNavAgent (executes skill calls)
5. Memory store (LTM for contextual info)
6. Skills library (click, open_url, get_dom, extract_pdf, etc.)
7. Playwright Manager / WebDriver (controls Chrome)
8. External services
– Chrome instance (remote debugging)
– OpenAI API
– LangSmith (optional)
9. User preferences file (resume path, filters)
10. Logger & Tracing
b. Relationships & interactions (data flow)
- User runs CLI → loads config & preferences → starts orchestrator
- Orchestrator invokes PlannerAgent with task + memory → PlannerAgent calls OpenAI → returns plan
- Orchestrator dispatches plan steps to BrowserNavAgent → BrowserNavAgent calls skill functions → skill uses Playwright Manager → remote Chrome
- Skill results (DOM snapshots, screenshots, URLs) → returned to orchestrator → memory updated
- Loop until task completion
- Orchestrator logs events and (optionally) sends traces to LangSmith
c. Architectural patterns / design principles
- Modular design: clear separation of concerns (orchestrator vs. agents vs. skills vs. infrastructure)
- Two orchestration patterns: conversational vs. finite-state machine
- Dependency inversion: agents depend on abstract skill interfaces, not concrete Playwright calls
- Extensibility: add new skills or agents without changing core orchestrator
d. Key technologies/frameworks
- Python 3.x
- Playwright (via jobber/core/playwright_manager or jobber_fsm/core/web_driver/playwright.py)
- OpenAI API for LLM calls
- Pydantic for config validation
- LangSmith for optional tracing
- CLI utilities (argparse or click via utils/cli_helper)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry
    subgraph "Entry Point"
        CLI_Jobber["CLI Entry (jobber)"]:::control
        CLI_FSM["CLI Entry (jobber_fsm)"]:::control
    end

    %% Configuration
    subgraph "Configuration"
        Config_Jobber["Config Loader (jobber)"]:::control
        Config_FSM["Config Loader (jobber_fsm)"]:::control
        UserPrefs_Jobber["User Preferences"]:::storage
        UserPrefs_FSM["User Preferences"]:::storage
    end

    %% Orchestrators
    subgraph "Orchestrators"
        Orch_Jobber["SystemOrchestrator"]:::control
        Orch_FSM["FSMOrchestrator"]:::control
    end

    %% Agents
    subgraph "Agents"
        Planner_Jobber["PlannerAgent"]:::control
        Planner_FSM["PlannerAgent"]:::control
        BrowserNav_Jobber["BrowserNavAgent"]:::control
        BrowserNav_FSM["BrowserNavAgent"]:::control
    end

    %% Core Libraries
    subgraph "Core Libraries"
        Memory_Jobber["LTM Memory"]:::functional
        Memory_FSM["LTM Memory"]:::functional
        Skills_Jobber["Skills Library"]:::functional
        Skills_FSM["Skills Library"]:::functional
        Prompts_Jobber["Prompt Templates"]:::functional
        Prompts_FSM["Prompt Templates"]:::functional
        Playwright_Jobber["Playwright Manager"]:::infra
        Playwright_FSM["WebDriver (Playwright)"]:::infra
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Chrome["Chrome Remote Debugging"]:::infra
        LangSmith["LangSmith"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        CLIHelper_Jobber["CLI Helpers"]:::functional
        Pydantic_Jobber["_Pydantic Models"]:::functional
        CLIHelper_FSM["CLI Helpers"]:::functional
        Pydantic_FSM["_Pydantic Models"]:::functional
    end

    %% Logging
    subgraph "Logging/Tracing"
        Logger["Logger"]:::infra
    end

    %% Connections
    CLI_Jobber --> Config_Jobber
    CLI_FSM --> Config_FSM
    Config_Jobber --> Orch_Jobber
    Config_FSM --> Orch_FSM
    Config_Jobber --> UserPrefs_Jobber
    Config_FSM --> UserPrefs_FSM
    Orch_Jobber --> Planner_Jobber
    Orch_FSM --> Planner_FSM
    Planner_Jobber --> OpenAI
    Planner_FSM --> OpenAI
    OpenAI --> Planner_Jobber
    OpenAI --> Planner_FSM
    Orch_Jobber --> BrowserNav_Jobber
    Orch_FSM --> BrowserNav_FSM
    BrowserNav_Jobber --> Skills_Jobber
    BrowserNav_FSM --> Skills_FSM
    Skills_Jobber --> Playwright_Jobber
    Skills_FSM --> Playwright_FSM
    Playwright_Jobber --> Chrome
    Playwright_FSM --> Chrome
    Skills_Jobber --> BrowserNav_Jobber
    Skills_FSM --> BrowserNav_FSM
    BrowserNav_Jobber --> Orch_Jobber
    BrowserNav_FSM --> Orch_FSM
    Orch_Jobber --> Memory_Jobber
    Orch_FSM --> Memory_FSM
    Planner_Jobber --> Memory_Jobber
    Planner_FSM --> Memory_FSM
    Orch_Jobber --> Logger
    Orch_FSM --> Logger
    Logger --> LangSmith

    %% Click Events
    click CLI_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/__main__.py"
    click CLI_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/__main__.py"
    click Config_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/config.py"
    click Config_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/config/config.py"
    click Orch_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/core/system_orchestrator.py"
    click Orch_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/core/orchestrator/orchestrator.py"
    click Planner_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/core/agents/planner_agent.py"
    click Planner_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/core/agent/planner_agent.py"
    click BrowserNav_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/core/agents/browser_nav_agent.py"
    click BrowserNav_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/core/agent/browser_nav_agent.py"
    click Memory_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/core/memory/ltm.py"
    click Memory_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/core/memory/ltm.py"
    click Skills_Jobber "https://github.com/sentient-engineering/jobber/tree/main/jobber/core/skills/"
    click Skills_FSM "https://github.com/sentient-engineering/jobber/tree/main/jobber_fsm/core/skills/"
    click Playwright_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/core/playwright_manager.py"
    click Playwright_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/core/web_driver/playwright.py"
    click Prompts_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/core/prompts.py"
    click Prompts_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/core/prompts/prompts.py"
    click UserPrefs_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/user_preferences/user_preferences.txt"
    click UserPrefs_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/user_preferences/user_preferences.txt"
    click CLIHelper_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/utils/cli_helper.py"
    click Pydantic_Jobber "https://github.com/sentient-engineering/jobber/blob/main/jobber/utils/_pydantic.py"
    click CLIHelper_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/utils/cli_helper.py"
    click Pydantic_FSM "https://github.com/sentient-engineering/jobber/blob/main/jobber_fsm/utils/_pydantic.py"

    %% Styles
    classDef control fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef functional fill:#E6F4EA,stroke:#027333,stroke-width:1px;
    classDef infra fill:#FFF4E5,stroke:#A60B00,stroke-width:1px;
    classDef external fill:#F3E8FF,stroke:#6f42c1,stroke-width:1px;
    classDef storage fill:#FFFFE0,stroke:#9a6e3a,stroke-width:1px;
```
