Introduction

I'm a second-year student at ZEN University studying intelligent informatics, and I want to become an AI engineer. I build AI agents as personal projects. I have no professional work experience as an engineer.

Yata (ヤタ) is a personal AI assistant that runs on your own computer. You talk to it in chat, in Japanese by default, and it can search the web, read pages, check mail and calendars, run scheduled jobs, and connect to services people often use in Japan. Conversations and memory stay in SQLite on the PC, not in a cloud of my own.

Up front: this is a beta. The README says it is early, and some things may not work well. This article is a record of the design so far, not a claim that the product is finished.

The code is MIT-licensed.

Why I built it

I wanted something in the same class as Grok Bot: an assistant that runs on my own PC, looks things up, acts only when it needs to, and stops before anything risky.

There are already many chat apps. The reasons to build my own were:

  1. Keep data local. History and a few long-term facts live on the user's PC from the start.
  2. Japanese first, including services people actually use in Japan. Not only Gmail and Google Calendar, but LINE, Chatwork, Backlog, kintone, freee, Money Forward Invoice, and Rakuten Ichiba.
  3. Ask before anything leaves the machine. Sending mail or creating an event should never happen just because the model decided to.

The name comes from Yatagarasu (八咫烏), the sacred three-legged crow that, in tradition, guided Emperor Jimmu. The role I wanted was a guide that shows the way. The mascot is a round purple baby crow; I gave it two legs, because I wanted it to feel friendly rather than strictly mythological.

The first commits used the name 灯 (Tomoshibi, "lamp"). I renamed it to Yata on the same day, once the "guide" image felt right.

I also wanted one project that I could use every day while studying, show as a portfolio piece, and later hand to other people. This is the first version that tries to do all three.

How I built it

I started Yata in Grok Bot and finished it with Claude. I gave instructions and wrote the code by talking with those tools. I don't have a clean record of which parts each one wrote, or of why I switched, so I won't invent one. The public repository is the result of that process.

What it can do

These are the capabilities described in the README:

  • Research: web search through DuckDuckGo (ddgs, no API key), then fetch a page and extract the main text
  • Mail and calendar: search, read, and draft Gmail; list events and check free/busy on Google Calendar. Sending mail and creating, updating, or deleting events wait for confirmation
  • Chat from LINE: you can message Yata from the LINE app. Risky actions show Allow / Deny buttons
  • Connectors for work in Japan: Chatwork messages and tasks, Backlog issues, kintone records, freee, Money Forward Invoice, LINE Official Account broadcasts, and Rakuten Ichiba product search
  • Japanese business calculations: holidays, business days, the Japanese imperial calendar, and qualified invoice (invoice system) consumption tax. It also writes polite Japanese
  • Routines: a request like "summarize the news at 8:00 every morning" runs at that time. The result can also be sent to LINE
  • Memory: short facts about you are stored and injected into the next system prompt
  • Browser control: a headless Chromium page per conversation, via Playwright (open, extract, click, type, screenshot). Clicks and typing wait for confirmation

You choose the model. You can bring one API key for Gemini, OpenAI, Anthropic, xAI (Grok), DeepSeek, Kimi, Mistral, Groq, OpenRouter, or PLaMo, or run a local model through Ollama, LM Studio, llama.cpp, Jan, vLLM, LocalAI, and other OpenAI-compatible servers. Gemini's free tier or a local model can make it free to run. If you have no key, a built-in demo model still exercises the real loop and the real tools; it is not there to judge answer quality.

An offline mode in settings uses only a local model and disables web search, the browser, external connectors, and LINE notifications, so the conversation does not leave the PC.

Architecture

The backend is Python 3.11+ and FastAPI, managed with uv. The UI is React, TypeScript, Tailwind CSS, Vite, and shadcn/ui. The agent loop, Playwright, and SQLite live in one process. After npm run build, FastAPI serves the UI on the same port (default http://127.0.0.1:8741).

flowchart TB UI["Chat UI<br/>React + TypeScript"] API["FastAPI<br/>chat, SSE, confirmations"] Loop["Agent loop"] Policy["ToolPolicy"] Gate["ConfirmationGate"] Router["ModelRouter"] Registry["ToolRegistry"] DB[("SQLite<br/>conversations and facts")] UI -->|message| API UI -->|allow / deny| Gate API --> Loop API --> DB Loop --> Router Loop --> Policy Policy --> Gate Loop --> Registry

One turn is: think, call a tool, observe, think again. The default cap is 8 model calls (YATA_MAX_STEPS). Intermediate events such as tool_call, confirmation_required, tool_result, and answer are streamed to the chat as Server-Sent Events.

The main packages are:

Path Role
src/yata/agent/loop.py Think, call a tool, observe, answer
src/yata/llm/ Provider adapters; vendor translation lives in convert.py
src/yata/tools/ Tool interface, registry, and risk
src/yata/confirm/gate.py Risky actions approved from a separate UI request
src/yata/memory/store.py SQLite for conversations and facts
src/yata/routines/ Stored routines and an in-process APScheduler
src/yata/connectors/ Auth and connections to outside services
src/yata/api/app.py HTTP and SSE; also serves the built UI
frontend/ Japanese chat UI

Design choices

1. Tools carry a risk; the loop only asks the policy

A tool is a class with a name, a JSON schema, a Risk, and run(). Adding one is a single registration in tools/catalog.py. There are four risks:

Risk Meaning Default
read Search, page fetch, screenshots, reading Gmail or the calendar Run immediately
write Local memory, creating a Gmail draft Run immediately
mutate Browser click and type Confirm first
external Sending mail, creating or changing events, sending messages, recording expenses, and so on Confirm first

The loop does not special-case tools. It asks ToolPolicy whether confirmation is required:

CONFIRM_RISKS = {Risk.MUTATE, Risk.EXTERNAL} class ToolPolicy: def needs_confirmation(self, tool: Tool, arguments: dict) -> bool: del arguments return tool.risk in CONFIRM_RISKS 

If it is, the loop first yields confirmation_required so the UI can show Allow / Deny, then waits. A denial or a timeout is not treated as approval.

The gate itself is an in-memory asyncio.Future that joins the agent loop to a later HTTP request from the UI (or from LINE). Timeouts fall closed: when in doubt, do not run. Because the gate lives in process memory, pending confirmations disappear if the server stops. That is still a rough edge.

Tools whose connector is not connected are hidden from the model (visible_registry()). The app still starts if a key is missing; those tools simply do not appear.

2. Official SDKs instead of a universal wrapper

A single wrapper such as LiteLLM was a real option. In this version I used the official SDKs (google-genai, openai, anthropic). The provider interface is only complete(messages, tools, model).

Vendor differences — especially how tool results are returned (OpenAI tool messages, Anthropic tool_result blocks, Gemini function_response parts) — stay in llm/convert.py, where they are readable. A wrapper would mean less code and more dependencies, and the conversion would be harder to see. This is a learning project and a portfolio piece, so I chose the seam I can read.

Ollama, LM Studio, vLLM, and other OpenAI-compatible servers reuse the OpenAI adapter with a different base_url. Providers without a key show up as unavailable, and the API rejects them before a request is sent.

For small local models, Yata uses a shorter system prompt (COMPACT_PROMPT), because a long brief makes it easier for a small model to lose the thread. Browser tools are also withheld from local models by default (YATA_LOCAL_BROWSER_TOOLS).

3. Keep the public surface small

Page fetching inspects the URL after every redirect. Cloud metadata addresses (169.254.169.254 and metadata.google.internal) are always blocked. Private hosts are controlled by YATA_ALLOW_PRIVATE_URLS (the personal default is true; turn it off before a public deploy).

The LINE webhook is a separate server on 127.0.0.1:8742 that exposes only /line/webhook and /line/health. Incoming events are limited by signature verification and an allowlist of user IDs. The tunnel publishes this webhook only. The main UI on port 8741 is not exposed.

cloudflared quick-tunnel URLs change on every start. Yata starts the tunnel itself and re-registers the webhook URL with LINE when it changes. You can turn that off with YATA_LINE_TUNNEL=false and run a tunnel by hand.

4. Routines run in the same process

If you type "summarize the news at 8:00 every morning," or add a routine from the sidebar, APScheduler in the same process calls the same agent loop. The default timezone is Asia/Tokyo.

You can close the browser tab. As long as the Yata process is still running, the job runs and the result is stored in that routine's conversation. Risky tools do not run unattended; they wait for confirmation until you open the app. If you turn on LINE notification for a routine, that notification is treated as something you already configured, so it is sent without a per-run confirmation.

There is not yet a Windows service or an OS notification. The process has to stay up. That is later on the roadmap.

What was hard, and what is still rough

The hardest part was not the agent loop. It was the first-time setup. Gmail and Calendar need a Google Cloud project, enabled APIs, an OAuth consent screen, a desktop-app client, and your account as a test user. LINE needs an Official Account, the Messaging API, allowed user IDs, and a tunnel. The more connectors I added, the longer the path became before I could use the app myself.

Other beta limits I want to be clear about:

  • Pending confirmations live in memory, so a restart drops them
  • Browser login state does not survive a restart (one headless page per conversation)
  • Routines only run while the Yata process is up
  • OS-level desktop control (moving the real mouse, and so on) is not implemented
  • The README has placeholders for screenshots and a demo GIF, but those files are not in the repo yet
  • The Microsoft Store listing is still marked as in preparation. GitHub Releases has v0.1.0 as Yata-Setup-0.1.0.exe and an MSIX. The Setup.exe is unsigned, so Windows may show "Windows protected your PC" until you choose More info → Run anyway

Tests run with uv run pytest and do not use the network or real API keys. They cover the agent loop, confirmations, provider conversion, memory, routines, and connectors, using mocks.

How to run it (Windows)

If you have uv, Node.js (the README says around 22), and Git, this PowerShell line is enough. The script tells you what is missing; it does not install tools on its own.

git clone https://github.com/koheip/yata.git; cd yata; powershell -ExecutionPolicy Bypass -File scripts\install.ps1 

Then start it with uv run yata. The first launch walks you through connecting an AI. If the app window does not open, visit http://127.0.0.1:8741.

For development, ./scripts/run.sh also works. Browser tools need uv run playwright install chromium. Search, reading, and memory work without it.

The installer is on Releases. App data for the packaged build lives under %LOCALAPPDATA%\Yata.

What is next

The roadmap treats the foundation (the loop, tools, the confirmation gate, and memory), in-process routines, and connectors including Gmail and Calendar as done. Later phases describe a desktop wrapper with a tray, auto-start, and OS notifications, and a hosted version whose routines would keep running when the PC is off. I am not treating planned work as if it already exists.

I want to use it every day, reduce setup friction, and fix the rough edges. Bug reports and ideas are welcome in GitHub Issues.