hiyal 0.0.1__tar.gz

hiyal-0.0.1/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  # Keep the workflow actions current.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "ci"

hiyal-0.0.1/.github/scripts/check_version.py

@@ -0,0 +1,29 @@
+"""Fail unless every place that states the version agrees.
+
+The version lives in pyproject.toml and in ``hiyal.__version__``. When a tag
+name is passed (``python check_version.py v0.1.0``), it must match too.
+"""
+
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[2]
+project = tomllib.loads((root / "pyproject.toml").read_text())["project"]["version"]
+match = re.search(
+    r'^__version__\s*=\s*["\']([^"\']+)["\']',
+    (root / "src/hiyal/__init__.py").read_text(),
+    re.MULTILINE,
+)
+package = match.group(1) if match else None
+
+versions = {"pyproject.toml": project, "hiyal.__version__": package}
+if len(sys.argv) > 1:
+    versions["git tag"] = sys.argv[1].removeprefix("v")
+
+for source, value in versions.items():
+    print(f"{source:20} {value}")
+if len(set(versions.values())) != 1:
+    sys.exit("error: the versions above disagree")
+print("versions agree")

hiyal-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+  # The release workflow runs the whole suite before publishing.
+  workflow_call:
+  # Weekly run: the SDKs are only lower-bounded, so a new release of
+  # openai/anthropic/google-genai/ollama can break us without a commit.
+  schedule:
+    - cron: "17 5 * * 1"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      # Pinned: ruff changes its default rules between releases. Bump on purpose.
+      - run: uvx ruff@0.17.4 check .
+
+  test:
+    name: Test (Python ${{ matrix.python }}, ${{ matrix.resolution }} dependencies)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+        resolution: [highest]
+        include:
+          # The oldest versions pyproject.toml allows must really work.
+          - python: "3.12"
+            resolution: lowest-direct
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - name: Run the tests
+        run: uv run --isolated --python ${{ matrix.python }} --resolution ${{ matrix.resolution }} pytest -ra
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - name: Run the tests with coverage
+        run: >
+          uv run --isolated --python 3.12 --with pytest-cov
+          pytest --cov=hiyal --cov-branch --cov-report=term-missing:skip-covered
+          --cov-report=xml --cov-fail-under=95
+      - uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report
+          path: coverage.xml
+
+  build:
+    name: Build and check the package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - name: Versions agree
+        run: uv run --no-project --python 3.12 python .github/scripts/check_version.py
+      - name: Build the sdist and wheel
+        run: uv build
+      - name: Check the metadata
+        run: uvx twine check dist/*
+      - name: Install the wheel in a clean environment and import it
+        run: |
+          uv venv "$RUNNER_TEMP/smoke" --python 3.12
+          uv pip install --python "$RUNNER_TEMP/smoke/bin/python" dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/smoke/bin/python" -c "
+          import hiyal
+          from hiyal.models import LLM, AnthropicLLM, DeepSeekLLM, GeminiLLM, OllamaLLM, OpenAILLM
+          from hiyal.prompts import UserPrompt
+          from hiyal.tools import tool
+          from hiyal.models.openai import ChatCompletionsTranslator
+          print('hiyal', hiyal.__version__, 'imports OK')
+          "
+      - uses: actions/upload-artifact@v7
+        with:
+          # Not "dist": release.yml calls this workflow and uploads its own "dist"
+          # in the same run, and artifact names must be unique within a run.
+          name: dist-ci
+          path: dist/
+          if-no-files-found: error
+
+  # One stable name for branch protection: require "CI passed" and nothing else.
+  ci-passed:
+    name: CI passed
+    if: always()
+    needs: [lint, test, coverage, build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail if any job failed or was cancelled
+        env:
+          BAD: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+          RESULTS: ${{ join(needs.*.result, ' ') }}
+        run: |
+          echo "job results: $RESULTS"
+          test "$BAD" = "false"

hiyal-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,109 @@
+name: Release
+
+# Publishing a release:
+#   1. Bump the version in pyproject.toml and src/hiyal/__init__.py, merge to master.
+#   2. git tag v<version> && git push origin v<version>
+# That runs the full test suite, builds the package, publishes it to PyPI
+# (after approval of the "pypi" environment) and creates the GitHub release.
+#
+# To rehearse on TestPyPI without a tag, run this workflow by hand from the
+# Actions tab; it publishes the current master to TestPyPI only.
+
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  ci:
+    name: Tests
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: Build distributions
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - name: The tag, pyproject.toml and hiyal.__version__ agree
+        if: github.ref_type == 'tag'
+        run: uv run --no-project --python 3.12 python .github/scripts/check_version.py "$GITHUB_REF_NAME"
+      - name: The versions agree
+        if: github.ref_type != 'tag'
+        run: uv run --no-project --python 3.12 python .github/scripts/check_version.py
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.ref_type == 'tag'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hiyal/
+    permissions:
+      id-token: write # trusted publishing: no API token is stored anywhere
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create the GitHub release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          # 0.1.0a1, 0.1.0rc1, 0.1.0.dev1 ... are pre-releases.
+          flags=""
+          if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then flags="--prerelease"; fi
+          gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" \
+            --title "$TAG" --generate-notes --verify-tag $flags
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/hiyal/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true

hiyal-0.0.1/.gitignore

@@ -0,0 +1,22 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+uv.lock
+.env
+# Files written by the multimodal notebooks
+multimodal/outputs/
+
+private/
+# Test and tool output
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.ruff_cache/

hiyal-0.0.1/.python-version

@@ -0,0 +1 @@
+3.12

hiyal-0.0.1/LICENSE

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

hiyal-0.0.1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: hiyal
+Version: 0.0.1
+Summary: Hiyal is an agentic tool. Currently it provides the LLM call component.
+Project-URL: Homepage, https://github.com/okanyenigun/hiyal
+Project-URL: Repository, https://github.com/okanyenigun/hiyal
+Project-URL: Issues, https://github.com/okanyenigun/hiyal/issues
+Author: Okan Yenigün
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,deepseek,gemini,llm,ollama,openai,streaming,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=1.9.0
+Requires-Dist: docstring-parser>=0.18.0
+Requires-Dist: google-genai>=2.25.0
+Requires-Dist: ollama>=0.6.2
+Requires-Dist: openai>=3.22.1
+Requires-Dist: pydantic>=2.12
+Requires-Dist: python-dotenv>=1.2.3
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/okanyenigun/hiyal/master/docs/assets/logo.png" alt="Hiyal" width="160">
+</p>
+
+# Hiyal
+
+Hiyal is an agentic tool. Right now it has only the LLM call component.
+
+## License
+
+[MIT](LICENSE) © Okan Yenigün

hiyal-0.0.1/README.md

@@ -0,0 +1,11 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/okanyenigun/hiyal/master/docs/assets/logo.png" alt="Hiyal" width="160">
+</p>
+
+# Hiyal
+
+Hiyal is an agentic tool. Right now it has only the LLM call component.
+
+## License
+
+[MIT](LICENSE) © Okan Yenigün

hiyal-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "hiyal"
+version = "0.0.1"
+description = "Hiyal is an agentic tool. Currently it provides the LLM call component."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Okan Yenigün" }]
+keywords = ["llm", "openai", "anthropic", "gemini", "ollama", "deepseek", "ai", "tool-calling", "streaming"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "anthropic>=1.9.0",
+    "docstring-parser>=0.18.0",
+    "google-genai>=2.25.0",
+    "ollama>=0.6.2",
+    "openai>=3.22.1",
+    "pydantic>=2.12",
+    "python-dotenv>=1.2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/okanyenigun/hiyal"
+Repository = "https://github.com/okanyenigun/hiyal"
+Issues = "https://github.com/okanyenigun/hiyal/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hiyal"]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.4.0",
+    "pytest>=9.2.0",
+]
+
+[tool.ruff.lint]
+# Only real errors: syntax errors, undefined names, unused imports and variables.
+# Style rules (import order, modernisation, ...) are deliberately not enforced.
+select = ["E4", "E7", "E9", "F"]

hiyal-0.0.1/src/hiyal/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

hiyal-0.0.1/src/hiyal/models/__init__.py

@@ -0,0 +1,20 @@
+from .anthropic import AnthropicLLM
+from .bases import BaseLLM
+from .deepseek import DeepSeekLLM
+from .gemini import GeminiLLM
+from .llm import LLM
+from .ollama import OllamaLLM
+from .openai import OpenAILLM
+from .schemas import LLMConfig, ThinkingConfig
+
+__all__ = [
+    "AnthropicLLM",
+    "BaseLLM",
+    "DeepSeekLLM",
+    "GeminiLLM",
+    "LLM",
+    "LLMConfig",
+    "OllamaLLM",
+    "OpenAILLM",
+    "ThinkingConfig",
+]

hiyal-0.0.1/src/hiyal/models/anthropic/__init__.py

@@ -0,0 +1,11 @@
+from .llm import AnthropicLLM
+from .translator import AnthropicStreamAccumulator, AnthropicTranslator
+from .transport import AnthropicFileStore, AnthropicTransport
+
+__all__ = [
+    "AnthropicFileStore",
+    "AnthropicLLM",
+    "AnthropicStreamAccumulator",
+    "AnthropicTranslator",
+    "AnthropicTransport",
+]

hiyal-0.0.1/src/hiyal/models/anthropic/llm.py

@@ -0,0 +1,23 @@
+from .translator import AnthropicTranslator
+from .transport import AnthropicTransport
+from ..bases import BaseLLM
+
+
+class AnthropicLLM(BaseLLM):
+    """Claude models via the Anthropic Messages API."""
+
+    provider = "anthropic"
+    display_name = "Anthropic"
+    # Claude reads images and documents; it has no audio input.
+    prompt_media = frozenset({"images", "documents"})
+    generation_adapter = {
+        "messages": "user_prompt",
+        "system": "system_prompt",
+        "max_tokens": "max_output_tokens",
+    }
+
+    def _create_translator(self) -> AnthropicTranslator:
+        return AnthropicTranslator(self.info)
+
+    def _create_transport(self) -> AnthropicTransport:
+        return AnthropicTransport(config=self.config, info=self.info)

hiyal-0.0.1/src/hiyal/models/anthropic/thinking.py

@@ -0,0 +1,63 @@
+"""Claude thinking controls: ``thinking={"type": ...}`` plus ``output_config.effort``."""
+
+import re
+from typing import Any
+
+from ...utility import Dicts
+from ..schemas import ThinkingConfig, UnsupportedThinkingError
+
+_VERSION = re.compile(r"claude-(?:opus|sonnet|haiku)-(\d+)(?:-(\d+))?")
+# Models whose thinking cannot be switched off.
+_ALWAYS_THINKING = ("claude-fable-", "claude-mythos-", "claude-opus-5-5", "claude-sonnet-5-5")
+
+
+def apply_claude_thinking(params: dict[str, Any], thinking: ThinkingConfig, model: str) -> None:
+    options = {**Dicts.get(params, "thinking", copy=True), **thinking.others}
+    output = Dicts.get(params, "output_config", copy=True)
+    mode = thinking.mode
+    if thinking.budget is not None and mode != "disabled":
+        options["budget_tokens"] = thinking.budget
+        mode = mode or "enabled"
+    version = _VERSION.search(model)
+    number = None if version is None else tuple(int(n or 0) for n in version.groups())
+    # Before 4.6 only manual budgets exist; from 4.7 only adaptive thinking.
+    legacy = number is not None and number < (4, 6)
+    manual_unsupported = number is not None and number >= (4, 7)
+    if mode == "disabled":
+        if model.startswith(_ALWAYS_THINKING):
+            raise UnsupportedThinkingError("Claude", model, "thinking cannot be fully disabled; use a supported native mode explicitly")
+        options = {key: value for key, value in options.items() if key != "budget_tokens"}
+        options["type"] = "disabled"
+        output.pop("effort", None)
+    else:
+        if thinking.effort is not None:
+            output["effort"] = thinking.effort
+        if mode == "enabled":
+            if legacy or "budget_tokens" in options:
+                if manual_unsupported:
+                    raise UnsupportedThinkingError("Claude", model, "manual thinking budgets are not supported; use adaptive mode")
+                budget = options.get("budget_tokens")
+                if type(budget) is not int or budget < 1024:
+                    raise UnsupportedThinkingError("Claude", model, "manual thinking requires thinking_budget (budget_tokens) >= 1024")
+                if params.get("max_tokens", params.get("max_output_tokens")) is None:
+                    raise UnsupportedThinkingError("Claude", model, "manual thinking requires an explicit max_output_tokens allowance")
+                options["type"] = "enabled"
+            else:
+                options["type"] = "adaptive"
+        elif mode is not None:
+            if mode == "adaptive" and legacy:
+                raise UnsupportedThinkingError("Claude", model, "adaptive thinking is not supported by this model")
+            if mode == "adaptive" and "budget_tokens" in options:
+                raise UnsupportedThinkingError("Claude", model, "adaptive thinking uses effort, not budget_tokens")
+            if mode == "between_tools":
+                if not model.startswith("claude-sonnet-5-5"):
+                    raise UnsupportedThinkingError("Claude", model, "between_tools is not supported by this model")
+                if output.get("effort") in {"xhigh", "max"}:
+                    raise UnsupportedThinkingError("Claude", model, "between_tools does not support xhigh/max effort")
+            options["type"] = mode
+    if options:
+        params["thinking"] = options
+    if output:
+        params["output_config"] = output
+    else:
+        params.pop("output_config", None)