teafyi 0.1.0__tar.gz

teafyi-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/

teafyi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FYIPedia
+
+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.

teafyi-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: teafyi
+Version: 0.1.0
+Summary: Tea knowledge API client — search tea varieties, processing methods, and terms from TeaFYI.
+Project-URL: Homepage, https://teafyi.com
+Project-URL: Documentation, https://teafyi.com/developers/
+Project-URL: Repository, https://github.com/fyipedia/teafyi
+Project-URL: Issues, https://github.com/fyipedia/teafyi/issues
+Project-URL: Changelog, https://github.com/fyipedia/teafyi/releases
+Author: FYIPedia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: black-tea,caffeine,green-tea,herbal-tea,matcha,oolong,steeping,tea,tea-ceremony,teaware
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: typer>=0.15; extra == 'all'
+Provides-Extra: api
+Requires-Dist: httpx>=0.27; extra == 'api'
+Provides-Extra: cli
+Requires-Dist: rich>=13.0; extra == 'cli'
+Requires-Dist: typer>=0.15; extra == 'cli'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# teafyi
+
+Tea knowledge API client for developers -- search tea varieties, processing methods, and terminology from [TeaFYI](https://teafyi.com).
+
+## Install
+
+```bash
+pip install teafyi[api]     # API client (httpx)
+pip install teafyi[cli]     # + CLI (typer, rich)
+pip install teafyi[mcp]     # + MCP server
+pip install teafyi[all]     # Everything
+```
+
+## Quick Start
+
+```python
+from teafyi.api import TeaFYI
+
+with TeaFYI() as api:
+    results = api.search("matcha")
+    print(results)
+```
+
+## CLI
+
+```bash
+teafyi search "matcha"
+teafyi search "oolong"
+teafyi search "gongfu ceremony"
+```
+
+## MCP Server
+
+```bash
+# Add to Claude Desktop config
+python -m teafyi.mcp_server
+```
+
+Tools: `tea_search`
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `search(query)` | `GET /api/search/?q=...` | Search teas, varieties, and terms |
+
+## Links
+
+- [TeaFYI](https://teafyi.com) -- Tea encyclopedia with categories, varieties, processing methods, and more
+- [PyPI](https://pypi.org/project/teafyi/)
+- [GitHub](https://github.com/fyipedia/teafyi)
+- [FYIPedia](https://fyipedia.com) -- Open-source developer tools ecosystem

teafyi-0.1.0/README.md

@@ -0,0 +1,52 @@
+# teafyi
+
+Tea knowledge API client for developers -- search tea varieties, processing methods, and terminology from [TeaFYI](https://teafyi.com).
+
+## Install
+
+```bash
+pip install teafyi[api]     # API client (httpx)
+pip install teafyi[cli]     # + CLI (typer, rich)
+pip install teafyi[mcp]     # + MCP server
+pip install teafyi[all]     # Everything
+```
+
+## Quick Start
+
+```python
+from teafyi.api import TeaFYI
+
+with TeaFYI() as api:
+    results = api.search("matcha")
+    print(results)
+```
+
+## CLI
+
+```bash
+teafyi search "matcha"
+teafyi search "oolong"
+teafyi search "gongfu ceremony"
+```
+
+## MCP Server
+
+```bash
+# Add to Claude Desktop config
+python -m teafyi.mcp_server
+```
+
+Tools: `tea_search`
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `search(query)` | `GET /api/search/?q=...` | Search teas, varieties, and terms |
+
+## Links
+
+- [TeaFYI](https://teafyi.com) -- Tea encyclopedia with categories, varieties, processing methods, and more
+- [PyPI](https://pypi.org/project/teafyi/)
+- [GitHub](https://github.com/fyipedia/teafyi)
+- [FYIPedia](https://fyipedia.com) -- Open-source developer tools ecosystem

teafyi-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "teafyi"
+version = "0.1.0"
+description = "Tea knowledge API client — search tea varieties, processing methods, and terms from TeaFYI."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "FYIPedia" }]
+keywords = [
+    "tea",
+    "green-tea",
+    "black-tea",
+    "oolong",
+    "matcha",
+    "herbal-tea",
+    "tea-ceremony",
+    "teaware",
+    "caffeine",
+    "steeping",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+    "Environment :: Console",
+]
+dependencies = []
+
+[project.optional-dependencies]
+api = ["httpx>=0.27"]
+cli = ["typer>=0.15", "rich>=13.0"]
+mcp = ["mcp>=1.0"]
+all = ["teafyi[api,cli,mcp]"]
+
+[project.scripts]
+teafyi = "teafyi.cli:app"
+
+[project.entry-points."mcp.servers"]
+teafyi = "teafyi.mcp_server:mcp"
+
+[project.urls]
+Homepage = "https://teafyi.com"
+Documentation = "https://teafyi.com/developers/"
+Repository = "https://github.com/fyipedia/teafyi"
+Issues = "https://github.com/fyipedia/teafyi/issues"
+Changelog = "https://github.com/fyipedia/teafyi/releases"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/teafyi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["RUF022"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[dependency-groups]
+dev = [
+    "httpx>=0.27",
+    "mcp>=1.0",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "rich>=13.0",
+    "ruff>=0.15.4",
+    "typer>=0.15",
+]

teafyi-0.1.0/skills/tea-tools/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: tea-tools
+description: Search 200+ tea varieties across 6 categories (white, green, oolong, black, dark, herbal) with chemistry, brewing guides, and origin data.
+---
+
+# Tea Tools
+
+Tea variety search and reference powered by [teafyi](https://teafyi.com/) -- a comprehensive tea knowledge platform covering 200+ varieties across 6 oxidation-based categories.
+
+## Setup
+
+Install the MCP server:
+
+```bash
+pip install "teafyi[mcp]"
+```
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "teafyi": {
+            "command": "python",
+            "args": ["-m", "teafyi.mcp_server"]
+        }
+    }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `tea_search` | Search tea varieties, categories, regions, processing methods, and terminology |
+
+## When to Use
+
+- Looking up tea varieties and their flavor profiles
+- Researching tea categories by oxidation level (white → green → oolong → black → dark)
+- Finding optimal brewing parameters (temperature, time, leaf-to-water ratio)
+- Exploring tea chemistry (L-theanine, catechins, caffeine, theaflavins)
+- Learning about tea origins and terroir (Darjeeling, Wuyi, Uji, Assam, etc.)
+
+## Links
+
+- [200+ Tea Varieties](https://teafyi.com/teas/)
+- [6 Tea Categories](https://teafyi.com/categories/)
+- [Tea Regions](https://teafyi.com/regions/)
+- [API Documentation](https://teafyi.com/developers/)
+- [PyPI Package](https://pypi.org/project/teafyi/)

teafyi-0.1.0/src/teafyi/__init__.py

@@ -0,0 +1,14 @@
+"""teafyi — Tea knowledge API client for developers.
+
+Search tea varieties, processing methods, and terminology from TeaFYI.
+
+Usage::
+
+    from teafyi.api import TeaFYI
+
+    with TeaFYI() as api:
+        results = api.search("matcha")
+        print(results)
+"""
+
+__version__ = "0.1.0"

teafyi-0.1.0/src/teafyi/api.py

@@ -0,0 +1,64 @@
+"""HTTP API client for teafyi.com REST endpoints.
+
+Requires the ``api`` extra: ``pip install teafyi[api]``
+
+Usage::
+
+    from teafyi.api import TeaFYI
+
+    with TeaFYI() as api:
+        results = api.search("matcha")
+        print(results)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class TeaFYI:
+    """API client for the teafyi.com REST API.
+
+    Args:
+        base_url: API base URL. Defaults to ``https://teafyi.com``.
+        timeout: Request timeout in seconds. Defaults to ``10.0``.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://teafyi.com",
+        timeout: float = 10.0,
+    ) -> None:
+        self._client = httpx.Client(base_url=base_url, timeout=timeout)
+
+    # -- HTTP helpers ----------------------------------------------------------
+
+    def _get(self, path: str, **params: Any) -> dict[str, Any]:
+        resp = self._client.get(path, params={k: v for k, v in params.items() if v is not None})
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+
+    # -- Endpoints -------------------------------------------------------------
+
+    def search(self, query: str) -> dict[str, Any]:
+        """Search teas, varieties, and glossary terms.
+
+        Args:
+            query: Search term (e.g. ``"matcha"``, ``"oolong"``).
+        """
+        return self._get("/api/search/", q=query)
+
+    # -- Context manager -------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._client.close()
+
+    def __enter__(self) -> TeaFYI:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

teafyi-0.1.0/src/teafyi/cli.py

@@ -0,0 +1,56 @@
+"""Command-line interface for teafyi.
+
+Requires the ``cli`` extra: ``pip install teafyi[cli]``
+
+Usage::
+
+    teafyi search "matcha"
+    teafyi search "oolong"
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(
+    name="teafyi",
+    help="Tea knowledge API client — search tea varieties, processing methods, and terms.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(help="Search term (e.g. 'matcha', 'oolong', 'gongfu')"),
+) -> None:
+    """Search teas, varieties, and glossary terms from TeaFYI."""
+    from teafyi.api import TeaFYI
+
+    with TeaFYI() as api:
+        data = api.search(query)
+
+    results = data.get("results", [])
+    if not results:
+        console.print(f"[yellow]No results found for '{query}'[/yellow]")
+        return
+
+    table = Table(title=f"Search: {query}")
+    table.add_column("Type", style="cyan", no_wrap=True)
+    table.add_column("Name", style="bold")
+    table.add_column("URL")
+
+    for item in results:
+        table.add_row(
+            item.get("type", ""),
+            item.get("name", ""),
+            item.get("url", ""),
+        )
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

teafyi-0.1.0/src/teafyi/mcp_server.py

@@ -0,0 +1,65 @@
+"""MCP server for teafyi — tea knowledge tools for AI assistants.
+
+Requires the ``mcp`` extra: ``pip install teafyi[mcp]``
+
+Run as a standalone server::
+
+    python -m teafyi.mcp_server
+
+Or configure in ``claude_desktop_config.json``::
+
+    {
+        "mcpServers": {
+            "teafyi": {
+                "command": "python",
+                "args": ["-m", "teafyi.mcp_server"]
+            }
+        }
+    }
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("teafyi")
+
+
+@mcp.tool()
+def tea_search(query: str) -> str:
+    """Search teas, varieties, processing methods, and glossary terms from TeaFYI.
+
+    Covers green tea, black tea, oolong, white tea, pu-erh, matcha, herbal teas,
+    tea ceremony traditions, teaware, and more.
+
+    Args:
+        query: Search term (e.g. "matcha", "oolong", "gongfu ceremony").
+    """
+    from teafyi.api import TeaFYI
+
+    with TeaFYI() as api:
+        data = api.search(query)
+
+    results = data.get("results", [])
+    if not results:
+        return f"No results found for '{query}'."
+
+    lines = [
+        f"## Tea Search: {query}",
+        "",
+        f"Found {len(results)} result(s):",
+        "",
+        "| Type | Name | URL |",
+        "|------|------|-----|",
+    ]
+    for item in results:
+        item_type = item.get("type", "")
+        name = item.get("name", "")
+        url = item.get("url", "")
+        lines.append(f"| {item_type} | {name} | {url} |")
+
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    mcp.run()

teafyi-0.1.0/tests/test_api.py

@@ -0,0 +1,40 @@
+"""Tests for teafyi.api — API client initialization and URL construction."""
+
+from teafyi.api import TeaFYI
+
+
+class TestTeaFYIInit:
+    def test_default_base_url(self) -> None:
+        client = TeaFYI()
+        assert str(client._client.base_url) == "https://teafyi.com"
+        client.close()
+
+    def test_custom_base_url(self) -> None:
+        client = TeaFYI(base_url="https://custom.example.com")
+        assert str(client._client.base_url) == "https://custom.example.com"
+        client.close()
+
+    def test_default_timeout(self) -> None:
+        client = TeaFYI()
+        assert client._client.timeout.connect == 10.0
+        client.close()
+
+    def test_custom_timeout(self) -> None:
+        client = TeaFYI(timeout=30.0)
+        assert client._client.timeout.connect == 30.0
+        client.close()
+
+    def test_context_manager(self) -> None:
+        with TeaFYI() as api:
+            assert str(api._client.base_url) == "https://teafyi.com"
+
+
+class TestTeaFYIURLConstruction:
+    def test_search_url_path(self) -> None:
+        """Verify search method would call the correct path (without making HTTP requests)."""
+        client = TeaFYI()
+        # Build the request manually to verify URL construction
+        request = client._client.build_request("GET", "/api/search/", params={"q": "matcha"})
+        assert "/api/search/" in str(request.url)
+        assert "q=matcha" in str(request.url)
+        client.close()