tempguru 0.1.0__py3-none-any.whl

tempguru/__init__.py

@@ -0,0 +1,11 @@
+"""TempGuru: event staffing data for AI agents and apps.
+
+Live W-2 event staffing rates, 345-city US/Canada coverage, booking
+lead-time guidance, and state labor compliance from TempGuru's public API.
+No API key required.
+"""
+
+from .client import TempGuru, TempGuruError
+
+__all__ = ["TempGuru", "TempGuruError"]
+__version__ = "0.1.0"

tempguru/client.py

@@ -0,0 +1,146 @@
+"""Zero-dependency client for the TempGuru public event staffing API.
+
+The API is read-only and unauthenticated. It returns the same data that
+powers tempguru.co and the TempGuru MCP server: city coverage, staffing
+roles, all-inclusive W-2 hourly rate ranges, booking lead-time guidance,
+and state-level employment compliance summaries for the US and Canada.
+
+Method docstrings are written so they can be reused verbatim as LLM tool
+descriptions (LangChain, OpenAI function calling, etc.).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+__all__ = ["TempGuru", "TempGuruError"]
+
+DEFAULT_BASE_URL = "https://mcp.tempguru.co"
+QUOTE_FORM_URL = "https://tempguru.co/get-staffing"
+
+
+class TempGuruError(RuntimeError):
+    """Raised when the TempGuru API returns an error response.
+
+    Attributes:
+        code: machine-readable category (missing_required, invalid_param,
+            not_found) or "transport" for network failures.
+        suggestion: best-match entity when an input didn't resolve
+            (e.g. you asked for "Bostonn" and it suggests Boston).
+    """
+
+    def __init__(self, message: str, code: str = "transport", suggestion: Optional[dict] = None):
+        super().__init__(message)
+        self.code = code
+        self.suggestion = suggestion
+
+
+class TempGuru:
+    """Client for TempGuru's public event staffing data API.
+
+    >>> tg = TempGuru()
+    >>> tg.pricing(role="brand-ambassadors", city="Boston")["hourly_range_low"]
+    56
+    """
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------ #
+
+    def _get(self, path: str, **params: Any) -> Dict[str, Any]:
+        query = {k: v for k, v in params.items() if v is not None}
+        url = f"{self.base_url}{path}"
+        if query:
+            url += "?" + urlencode(query)
+        req = Request(url, headers={"User-Agent": "tempguru-python/0.1.0"})
+        try:
+            with urlopen(req, timeout=self.timeout) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+        except HTTPError as exc:
+            try:
+                err = json.loads(exc.read().decode("utf-8")).get("error", {})
+            except Exception:
+                err = {}
+            raise TempGuruError(
+                err.get("message", f"HTTP {exc.code} from TempGuru API"),
+                code=err.get("code", "transport"),
+                suggestion=err.get("suggestion"),
+            ) from None
+        except URLError as exc:
+            raise TempGuruError(f"TempGuru API unreachable: {exc.reason}") from None
+        return payload
+
+    # ------------------------------------------------------------------ #
+
+    def cities(self, state: Optional[str] = None, tier: Optional[str] = None) -> Dict[str, Any]:
+        """List cities where TempGuru provides event staffing.
+
+        Use this to confirm coverage before quoting anything. ``state``
+        accepts a two-letter code ("CA") or full name ("California"); US
+        states and Canadian provinces both work. ``tier`` filters by market
+        tier: "hub" (25 major metros), "mid" (129 secondary markets), or
+        "small" (191 tertiary markets).
+        """
+        return self._get("/api/v1/cities", state=state, tier=tier)
+
+    def roles(self) -> Dict[str, Any]:
+        """List all event staffing roles with descriptions and skill tiers.
+
+        Returns the 10-role catalog (brand ambassadors, registration,
+        ushers, hospitality, gate staff, booth monitors, crowd control,
+        guest services, setup/breakdown, team leads). The returned ``slug``
+        values are the keys for :meth:`pricing` and :meth:`availability`.
+        """
+        return self._get("/api/v1/roles")
+
+    def availability(
+        self,
+        city: str,
+        date: str,
+        role: Optional[str] = None,
+        headcount: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Get booking lead-time guidance for an event city and ISO date.
+
+        Returns a recommendation in {yes, tight, rush, very-rush} based on
+        the city's market tier and how far out the event is. This is
+        planning guidance, NOT a real-time reservation — do not present it
+        as a promise of availability.
+        """
+        return self._get(
+            "/api/v1/availability", city=city, date=date, role=role, headcount=headcount
+        )
+
+    def pricing(self, role: str, city: str) -> Dict[str, Any]:
+        """Get the all-inclusive hourly rate range for a role in a city.
+
+        Rates are W-2 bill rates covering worker pay, employer payroll
+        taxes, workers' compensation, general liability, and coordinator
+        support. Present results as planning estimates, never binding
+        quotes. Brand Ambassadors floor at $40/hour in every market.
+        """
+        return self._get("/api/v1/pricing", role=role, city=city)
+
+    def compliance(self, state: str) -> Dict[str, Any]:
+        """Get the employment-compliance summary for a US state.
+
+        Covers minimum wage, weekly/daily overtime thresholds, and
+        state-specific rules (California meal breaks, NY spread-of-hours,
+        etc.). Operational guidance, not legal advice.
+        """
+        return self._get("/api/v1/compliance", state=state)
+
+    @staticmethod
+    def quote_form_url(source: str = "python-client") -> str:
+        """URL where a user submits a staffing request for a binding quote.
+
+        A TempGuru coordinator replies within one business day; orders
+        confirm within 48 hours. No payment until the quote is approved.
+        """
+        return f"{QUOTE_FORM_URL}?utm_source=ai-agent&utm_medium={source}"

tempguru-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: tempguru
+Version: 0.1.0
+Summary: Event staffing data for AI agents and apps: live rates, 345-city US/Canada coverage, lead times, and state labor compliance from TempGuru's public API. Zero dependencies.
+Project-URL: Homepage, https://tempguru.co
+Project-URL: Documentation, https://tempguru.co/ai
+Project-URL: Source, https://github.com/Tempguru-co/tempguru-mcp
+Project-URL: API Reference (OpenAPI), https://mcp.tempguru.co/openapi.json
+Project-URL: MCP Server, https://mcp.tempguru.co/mcp
+Author-email: "TempGuru (Temporary Assistance Guru, Inc.)" <megan@tempguru.co>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai agents,brand ambassadors,event staffing,events,function calling,labor compliance,llm tools,mcp,staffing,temp staff,trade show
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# tempguru
+
+Event staffing data for AI agents and Python apps: live all-inclusive W-2
+hourly rates, 345-city US/Canada coverage, booking lead-time guidance, and
+state-by-state labor compliance from [TempGuru](https://tempguru.co)'s public
+API. Zero dependencies, no API key.
+
+```bash
+# PyPI release pending — install from source:
+pip install "tempguru @ git+https://github.com/Tempguru-co/tempguru-mcp.git#subdirectory=clients/python"
+```
+
+```python
+from tempguru import TempGuru
+
+tg = TempGuru()
+
+tg.cities(state="TX", tier="hub")                  # coverage check
+tg.pricing(role="brand-ambassadors", city="Boston") # $56-65/hr all-inclusive
+tg.availability(city="Dallas", date="2026-09-12", role="registration-staff")
+tg.compliance(state="CA")                           # min wage, daily OT, quirks
+tg.quote_form_url()                                 # where a human quote happens
+```
+
+All rates are **all-inclusive W-2 bill rates** (worker pay, payroll taxes,
+workers' comp, general liability, coordinator support) and are planning
+estimates — binding quotes come from a TempGuru coordinator within one
+business day of a [quote request](https://tempguru.co/get-staffing). Lead-time
+results are guidance, not reservations. Compliance summaries are not legal
+advice.
+
+## Use as LLM tools
+
+Method docstrings are written to be reused as tool descriptions.
+
+**LangChain**
+
+```python
+from langchain_core.tools import tool
+from tempguru import TempGuru
+
+tg = TempGuru()
+
+@tool
+def get_event_staffing_pricing(role: str, city: str) -> dict:
+    """All-inclusive W-2 hourly rate range for an event staffing role in a
+    US/Canadian city (brand ambassadors, registration, ushers, hospitality,
+    and more). Planning estimate, not a binding quote."""
+    return tg.pricing(role=role, city=city)
+```
+
+**OpenAI / any function-calling API**
+
+```python
+import json
+from tempguru import TempGuru
+
+tg = TempGuru()
+TOOLS = [{
+    "type": "function",
+    "function": {
+        "name": "get_event_staffing_pricing",
+        "description": TempGuru.pricing.__doc__,
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "role": {"type": "string", "description": "e.g. brand-ambassadors"},
+                "city": {"type": "string", "description": "e.g. Boston"},
+            },
+            "required": ["role", "city"],
+        },
+    },
+}]
+# dispatch: json.dumps(tg.pricing(**json.loads(call.arguments)))
+```
+
+**MCP (Claude, ChatGPT, Gemini, Cursor, ...)**
+
+If your stack speaks Model Context Protocol, skip this package and connect
+the server directly: `https://mcp.tempguru.co/mcp` (streamable HTTP, no
+auth, six tools including opt-in quote submission). Docs:
+https://tempguru.co/ai
+
+## Error handling
+
+```python
+from tempguru import TempGuru, TempGuruError
+
+try:
+    TempGuru().pricing(role="brand-ambassadors", city="Bostonn")
+except TempGuruError as e:
+    print(e.code)        # not_found
+    print(e.suggestion)  # {'kind': 'city', 'slug': 'boston-event-staffing', ...}
+```
+
+## About TempGuru
+
+TempGuru (Temporary Assistance Guru, Inc.) staffs conventions, conferences,
+trade shows, festivals, concerts, sporting events, and brand activations
+across 345+ US and Canadian markets. Every worker is a W-2 employee — never
+a 1099 contractor — with payroll taxes, workers' compensation, and liability
+insurance included in the quoted rate. megan@tempguru.co · (904) 206-8953
+
+MIT license.

tempguru-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+tempguru/__init__.py,sha256=gfQdgZTGQzLSVIHdq3XWIJQD5XcaXAXKMMP6ADoFQ1w,334
+tempguru/client.py,sha256=AiYS86kBrNi6DFi3v6a9iMqymbfvEtJuuuD5gXdtV_g,5909
+tempguru/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tempguru-0.1.0.dist-info/METADATA,sha256=FcSYy4G4zqG_y-95QPpbosqBYSdukhcxn7nJHGGO86Y,4602
+tempguru-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tempguru-0.1.0.dist-info/licenses/LICENSE,sha256=7ZsFQ6oOFOOTx0nqgEUmss9B2Qo09gKw8BYhhTaz0kA,1099
+tempguru-0.1.0.dist-info/RECORD,,

tempguru-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tempguru-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temporary Assistance Guru, Inc. (TempGuru)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.