{"id":50771796,"url":"https://github.com/ggueret/koina","last_synced_at":"2026-06-11T19:31:45.272Z","repository":{"id":364075204,"uuid":"1262403241","full_name":"ggueret/koina","owner":"ggueret","description":"An agentic toolset: provider-neutral tools and dispatch for building agents on low-level LLM SDKs","archived":false,"fork":false,"pushed_at":"2026-06-11T13:40:34.000Z","size":102,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T15:23:55.769Z","etag":null,"topics":["agentic","agents","ai","function-calling","llm","python","tool-use"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ggueret.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T00:27:49.000Z","updated_at":"2026-06-11T13:40:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ggueret/koina","commit_stats":null,"previous_names":["ggueret/koina"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ggueret/koina","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggueret%2Fkoina","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggueret%2Fkoina/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggueret%2Fkoina/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggueret%2Fkoina/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ggueret","download_url":"https://codeload.github.com/ggueret/koina/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggueret%2Fkoina/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34215253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","agents","ai","function-calling","llm","python","tool-use"],"created_at":"2026-06-11T19:31:45.067Z","updated_at":"2026-06-11T19:31:45.247Z","avatar_url":"https://github.com/ggueret.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/brand/wordmark-dark.svg\"\u003e\n    \u003cimg src=\"assets/brand/wordmark.svg\" alt=\"koina\" width=\"240\"\u003e\n  \u003c/picture\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eAn agentic toolset.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Reusable, provider-neutral building blocks for agents on low-level LLM SDKs:\n  the six core file/shell tools (Read, Write, Edit, Bash, Glob, Grep), a\n  never-raising \u003ccode\u003edispatch\u003c/code\u003e, structured JSONL logging, and a thin\n  adapter per provider. koina gives you the tools and the dispatch; the agentic\n  loop stays in your code.\n\u003c/p\u003e\n\n## Requirements\n\n- Python 3.12+\n- ripgrep (`rg`) on PATH (for Glob and Grep)\n\n## Install\n\n```bash\nuv add koina\n```\n\nThe library depends only on `pydantic`. Provider SDKs (`anthropic`, `openai`)\nare the caller's dependency, used in your loop, not by koina.\n\n## Usage\n\n`dispatch` and the tools are provider-neutral; an adapter translates a provider's\nwire format to and from the neutral `ToolCall`/`ToolResult`. With the Anthropic\nadapter:\n\n```python\nfrom pathlib import Path\nfrom anthropic import AsyncAnthropic\nfrom koina import default_registry, dispatch, ToolContext\nfrom koina.adapters import anthropic as adapter\n\nclient = AsyncAnthropic()\nreg = default_registry()\nctx = ToolContext(cwd=Path.cwd())\nmsgs = [{\"role\": \"user\", \"content\": \"List the Python files.\"}]\n\nwhile True:\n    resp = await client.messages.create(\n        model=\"claude-opus-4-8\", max_tokens=4096,\n        messages=msgs, tools=adapter.tools_param(reg),\n    )\n    msgs.append({\"role\": \"assistant\", \"content\": resp.content})\n    calls = adapter.parse_tool_calls(resp.content)\n    if not calls:\n        break\n    results = [await dispatch(c, reg, ctx) for c in calls]\n    msgs.append(adapter.format_results(results))\n```\n\nSwap `koina.adapters.anthropic` for `koina.adapters.openai` to run the same tools\nagainst the OpenAI Chat Completions API (or any OpenAI-compatible server, e.g.\nllama.cpp). See `examples/` for runnable read-only code-review scripts on both.\n\n## What's in the box\n\n- **Six core tools** (Read, Write, Edit, Bash, Glob, Grep), faithful to Claude\n  Code's observable behavior, headless (no permissions or hooks).\n- **`dispatch` never raises**: it always returns a `ToolResult` (errors set\n  `is_error=True`).\n- **Provider-neutral core** (`ToolCall`, `ToolResult`) with per-provider adapters\n  (`koina.adapters.anthropic`, `koina.adapters.openai`). The library never imports\n  a provider SDK at runtime.\n- **Structured logging**: typed events (tool calls, model calls, token usage,\n  reasoning) emitted to a pluggable `EventSink` (`JsonlSink`/`NullSink`), so a run\n  reconstructs from a JSONL transcript. Off by default, near-zero overhead when\n  inactive.\n\nPermissions, web tools, and concurrency orchestration are out of scope.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggueret%2Fkoina","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fggueret%2Fkoina","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggueret%2Fkoina/lists"}