humanhours (Python)

The ROI meter for your AI agents. One HTTP call per task, automatic proof of hours and euros saved.

pip install humanhours

60-second quickstart

from humanhours import Humanhours

hh = Humanhours(api_key="hh_live_...")

hh.track(
    agent_id="support-classifier",
    task_type="email_classification",
    outcome="success",
)

That's it. The dashboard at humanhours.dev shows the saved hours and euros.

Decorator

from humanhours import Humanhours, track

hh = Humanhours(api_key="...", default_agent_id="support-classifier")

@track(hh, task_type="email_classification")
def classify(subject: str) -> str:
    ...

The decorator times the function, captures the outcome (success on return, failure on raise), and reports automatically. Failures re-raise — your code keeps its normal control flow.

Ambient client (context manager)

with Humanhours(api_key="...") as hh:
    @track(task_type="contract_clause_review", agent_id="legal-clause-reviewer")
    def review_clause(text):
        ...
    review_clause("...")

@track without client= picks up the active with scope. Useful when you can't pass the client through a deep call tree.

Read your numbers

hh.summary(period="30d")
hh.agents()
hh.report("/time-saved", {"period": "30d", "group_by": "agent"})

Errors

from humanhours import Humanhours, HumanhoursError

try:
    hh.track(task_type="...", agent_id="...", outcome="success")
except HumanhoursError as e:
    if e.code == "unknown_task_type":
        ...
    raise

Configuration

The decorator also reads HUMANHOURS_API_KEY / HUMANHOURS_BASE_URL from the environment as a fallback.

License

MIT.