{"id":50752236,"url":"https://github.com/agentjido/jidoka","last_synced_at":"2026-06-11T02:05:08.314Z","repository":{"id":352762039,"uuid":"1215398789","full_name":"agentjido/jidoka","owner":"agentjido","description":"Developer-friendly LLM agent harness built on Jido and Jido AI","archived":false,"fork":false,"pushed_at":"2026-06-09T22:40:12.000Z","size":37528,"stargazers_count":10,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T00:12:34.527Z","etag":null,"topics":["agent-framework","ai-agents","application","developer-tools","elixir","elixir-package","jido","llm"],"latest_commit_sha":null,"homepage":"https://jido.run/ecosystem/jidoka","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentjido.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-19T21:27:32.000Z","updated_at":"2026-06-09T22:40:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agentjido/jidoka","commit_stats":null,"previous_names":["mikehostetler/moto","mikehostetler/jidoka","agentjido/jidoka"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/agentjido/jidoka","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentjido%2Fjidoka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentjido%2Fjidoka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentjido%2Fjidoka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentjido%2Fjidoka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentjido","download_url":"https://codeload.github.com/agentjido/jidoka/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentjido%2Fjidoka/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34178824,"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":["agent-framework","ai-agents","application","developer-tools","elixir","elixir-package","jido","llm"],"created_at":"2026-06-11T02:05:03.738Z","updated_at":"2026-06-11T02:05:08.307Z","avatar_url":"https://github.com/agentjido.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jidoka\n\n[![Hex.pm](https://img.shields.io/hexpm/v/jidoka.svg)](https://hex.pm/packages/jidoka)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/jidoka/)\n[![CI](https://github.com/agentjido/jidoka/actions/workflows/ci.yml/badge.svg)](https://github.com/agentjido/jidoka/actions/workflows/ci.yml)\n[![License](https://img.shields.io/hexpm/l/jidoka.svg)](https://github.com/agentjido/jidoka/blob/main/LICENSE)\n[![Website](https://img.shields.io/badge/website-jido.run-0f172a.svg)](https://jido.run)\n[![Ecosystem](https://img.shields.io/badge/ecosystem-jido.run-0ea5e9.svg)](https://jido.run/ecosystem)\n[![Discord](https://img.shields.io/badge/discord-join-5865F2.svg?logo=discord\u0026logoColor=white)](https://jido.run/discord)\n\n\u003e **A data-driven agent framework for the Jido ecosystem with a Spark DSL and durable turn runtime.**\n\nJidoka is a small Elixir agent framework for the Jido ecosystem.\n\nUse it when you want an application agent that can call a real LLM, expose\nJido actions as tools, keep turns inspectable, and pause safely for approval or\nresume later.\n\n```text\nDSL / JSON / YAML\n-\u003e Jidoka.Agent.Spec\n-\u003e Jidoka.chat / Jidoka.turn / Jidoka.Session\n-\u003e model calls + bounded tool-call batches\n-\u003e text, Turn.Result, or snapshot\n```\n\nJidoka keeps the authoring surface narrow: `agent`, `tools`, and `controls`.\nThe rest is data: specs, requests, results, journals, snapshots, sessions, and\nevents.\n\n## Install\n\nIf your project uses [Igniter](https://hex.pm/packages/igniter), install the\ncurrent beta from Hex:\n\n```bash\nmix igniter.install jidoka@0.8.0-beta.1\n```\n\nFor manual installation, add `jidoka` to your dependencies:\n\n```elixir\ndef deps do\n  [\n    {:jidoka, \"~\u003e 0.8.0-beta\"}\n  ]\nend\n```\n\n```bash\nmix deps.get\n```\n\nExport a provider key before running live examples:\n\n```bash\nexport OPENAI_API_KEY=...\n# or\nexport ANTHROPIC_API_KEY=...\n```\n\nJidoka does not load `.env` files for applications. Put that policy in your\napp, release config, example app, or shell.\n\nJidoka is beta software. The `0.8.x` beta line is intended for early adopters\nwhile the public API is still allowed to change before a stable release.\n\n## Define An Agent\n\n```elixir\ndefmodule MyApp.Assistant do\n  use Jidoka.Agent\n\n  agent :assistant do\n    model \"openai:gpt-4o-mini\"\n    instructions \"Answer clearly and briefly.\"\n  end\nend\n\n{:ok, text} = MyApp.Assistant.chat(\"What can you help me with?\")\n```\n\nUse `chat/3` when you only need the final assistant text. Use `turn/3` when\nyou need the full result, including journaled tool calls and events:\n\n```elixir\n{:ok, result} = Jidoka.turn(MyApp.Assistant, \"What can you help me with?\")\n\nresult.content\nresult.events\nresult.journal.results\n```\n\n## Add A Tool\n\nTools are Jido actions exposed to the model as operations.\n\n```elixir\ndefmodule MyApp.LocalTime do\n  use Jidoka.Action,\n    name: \"local_time\",\n    description: \"Returns the local time for a city.\",\n    schema: Zoi.object(%{city: Zoi.string() |\u003e Zoi.default(\"Chicago\")})\n\n  @impl true\n  def run(params, _context) do\n    city = Map.get(params, :city) || Map.get(params, \"city\") || \"Chicago\"\n    {:ok, %{city: city, time: \"09:30\"}}\n  end\nend\n\ndefmodule MyApp.TimeAgent do\n  use Jidoka.Agent\n\n  agent :time_agent do\n    model \"openai:gpt-4o-mini\"\n    instructions \"Use local_time when the user asks for the time.\"\n  end\n\n  tools do\n    action MyApp.LocalTime\n  end\nend\n\n{:ok, text} = MyApp.TimeAgent.chat(\"What time is it in Chicago?\")\n```\n\nThe model decides whether to call `local_time`. Jidoka runs the action, feeds\nthe observation back to the model, and returns the final answer.\n\n## Keep A Conversation\n\nUse `Jidoka.Session` when the same agent should answer across turns.\n\n```elixir\n{:ok, session} = Jidoka.session(MyApp.Assistant, \"support-thread-123\")\n\n{:ok, session, _text} =\n  Jidoka.chat(session, \"Remember that my team is called Platform.\")\n\n{:ok, session, text} =\n  Jidoka.chat(session, \"What is my team called?\")\n```\n\nSessions can run in memory for development and tests, or through a custom\nstore in production.\n\n## Pause For Approval\n\nControls run at explicit boundaries. An operation control can pause before a\nrisky tool call:\n\n```elixir\ndefmodule MyApp.RequireRefundApproval do\n  use Jidoka.Control, name: \"require_refund_approval\"\n\n  @impl true\n  def call(%Jidoka.Runtime.Controls.OperationContext{} = operation) do\n    if operation.operation == \"refund_order\" do\n      {:interrupt, :approval_required}\n    else\n      :cont\n    end\n  end\nend\n```\n\nAn interrupt returns a snapshot. Store it, review it, then resume:\n\n```elixir\n{:hibernate, snapshot} = Jidoka.turn(MyApp.SupportAgent, \"Refund order A1001\")\n\napproval =\n  snapshot.turn_state.pending_interrupt\n  |\u003e Jidoka.Review.Response.approve()\n\n{:ok, result} = Jidoka.resume(snapshot, approval: approval)\n```\n\n## Inspect Before You Spend Tokens\n\n```elixir\nJidoka.inspect(MyApp.TimeAgent)\n\n{:ok, preflight} =\n  Jidoka.preflight(MyApp.TimeAgent, \"What time is it in Chicago?\")\n\npreflight.prompt.messages\npreflight.prompt.tool_definitions\n```\n\n`preflight/3` validates the prompt and tool metadata without calling a model.\n\nAfter a turn, use `Jidoka.Debug.request/2` when you need the full request view\nfor a user report, notebook, or test:\n\n```elixir\n{:ok, result} = Jidoka.turn(MyApp.TimeAgent, \"What time is it in Chicago?\")\n{:ok, summary} = Jidoka.Debug.request(result)\n\nsummary.prompt.messages\nsummary.operation_results\nsummary.usage\nsummary.replay_diagnostics.status\n```\n\n## Author With Data\n\nAgents can also be imported from JSON or YAML:\n\n```yaml\nversion: 1\nagent:\n  id: assistant\n  model: openai:gpt-4o-mini\n  instructions: Answer clearly and briefly.\n```\n\n```elixir\n{:ok, spec} = Jidoka.import(yaml)\n{:ok, text} = Jidoka.chat(spec, \"Hello\")\n```\n\nExecutable refs such as actions, controls, Ash resources, and Zoi schemas are\nresolved through explicit registries during import.\n\n## Examples And Livebooks\n\nThe Phoenix showcase app lives in `example/`.\n\n```bash\ncd example\nmix deps.get\nmix phx.server\n```\n\nLivebooks live in `livebook/` and focus on contracts, controls, sessions,\nimports, evals, and trace output.\n\n## Test\n\n```bash\nmix test\nmix test --cover\nmix format --check-formatted\n```\n\nLive provider tests are opt-in:\n\n```bash\nmix test --include live test/jidoka/live_req_llm_test.exs\n```\n\nUnit tests should inject fake `llm:` and `operations:` capabilities. Product\nguides and examples should use real provider keys.\n\n## Guides\n\nStart here:\n\n- [Getting Started](guides/getting-started.md)\n- [Agent DSL](guides/agent-dsl.md)\n- [Tools And Operations](guides/tools-and-operations.md)\n- [Agent Orchestration](guides/agent-orchestration.md)\n- [Workflows](guides/workflows.md)\n- [Controls](guides/controls.md)\n- [Sessions And Stores](guides/sessions-and-stores.md)\n- [Inspection And Preflight](guides/inspection-and-preflight.md)\n- [Testing And Evals](guides/testing-and-evals.md)\n\nUseful next topics:\n\n- [Structured Results](guides/structured-results.md)\n- [Memory](guides/memory.md)\n- [Streaming](guides/streaming.md)\n- [Import JSON/YAML](guides/import-json-yaml.md)\n- [Inspection And Preflight](guides/inspection-and-preflight.md)\n\n## Status\n\nThis is the `1.0.0-beta.1` baseline. The public vocabulary is centered on:\n\n- `Jidoka.Agent.Spec`\n- `Jidoka.Turn.Request`, `Jidoka.Turn.Plan`, and `Jidoka.Turn.Result`\n- `Jidoka.Session`\n- `Jidoka.import/2`, `Jidoka.chat/3`, `Jidoka.turn/3`, `Jidoka.resume/2`\n- `tools`, `controls`, `memory`, `result`, `trace`, and `eval`\n\nNative provider tool calling, inline workflow sugar, and production\nstore/runtime adapters are still active design areas.\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentjido%2Fjidoka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentjido%2Fjidoka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentjido%2Fjidoka/lists"}