import ezos

ezos.open_app("spotify")                 # launches Spotify (Store app!)
ezos.play_on_youtube("lofi hip hop")     # finds + opens the first video
ezos.search_web("weather", browser="chrome")
print(ezos.weather("London"))            # "London: Overcast +12C, 84% humidity"
ezos.speak("All systems online, boss.")

✨ Why ezos?

When you point an AI at a computer, it needs simple, predictable verbs — not 40 lines of subprocess / ctypes / Win32 boilerplate per task. ezos gives it 85 of them, each named like plain English, each returning a structured result so the AI always knows what happened.

• 🎯 It actually works. App launching uses Windows' own Get-StartApps resolver, so Store apps (Spotify, ChatGPT) and desktop apps (Zoom, Discord) really launch — not just the ones on your PATH.
• 📦 Zero dependencies for the core. Launching, browser, media keys, window control, volume, weather, clipboard, speak — all work on a plain Python install.
• 🤖 Built for AI. Ships OpenAI-compatible + Claude tool formats, a config builder, and a ready-made Jarvis agent loop. Works with OpenAI, Gemini, Z.ai, Groq, and any OpenAI-format API.
• 🔎 Real web research with DuckDuckGo + BeautifulSoup — your AI can find things out, not just open a search page.
• 😌 Readable both ways. ezos.open_app() and ezos.openApp() both work.

📦 Install

git clone https://github.com/<your-username>/ezos.git
cd ezos
pip install -r requirements.txt     # optional extras; the core needs nothing

Or just drop ezos.py next to your script and import ezos.

🚀 Quick start

import ezos

# files
ezos.create_file("notes.txt", "hello world")
print(ezos.read_file("notes.txt"))

# apps & web
ezos.open_app("discord")
ezos.search_web("python tips", browser="chrome")

# system
print(ezos.system_info())
print(ezos.weather("Tokyo"))
ezos.volume_up(10)

# talk & notify
ezos.speak("Task complete")
ezos.reminder(600, "Take a break")       # pops + speaks in 10 min

Every action returns a structured result, so you always know what happened:

ezos.open_app("spotify")
# -> {"ok": True,  "message": "Opened 'Spotify'", "resolved": "Spotify"}
ezos.open_app("notarealapp")
# -> {"ok": False, "message": "Could not find an app called 'notarealapp'. ..."}
#    (also prints a visible  WARNING ezos: ...  so failures aren't silent)

🤖 Build your own Jarvis

ezos is the toolbox; your LLM is the brain. It works with any OpenAI-compatible provider — OpenAI, Google Gemini, Z.ai, Groq, Together, OpenRouter, local servers — just point the client's base_url at them.

1. Configure the AI

aiRead() makes one instruction block. Stack as many as you like and feed them to configure(), which also tells the AI which tools it has, with an instruction for each.

import ezos

cfg = ezos.configure(
    ezos.aiRead("Call me 'boss'."),
    ezos.aiRead("Prefer Chrome for browsing."),
    ezos.aiRead("Research before answering factual questions."),
    provider="openai",
)
cfg["system_prompt"]   # -> system message for your LLM
cfg["tools"]           # -> tools in the OpenAI-compatible format

2. Use the ready-made Jarvis loop

from openai import OpenAI
import ezos

# Google Gemini (via the OpenAI-compatible endpoint)
client = OpenAI(
    api_key="YOUR_GEMINI_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

jarvis = ezos.Jarvis(client, model="gemini-2.0-flash", instructions=[
    ezos.aiRead("Call me boss."),
    ezos.aiRead("Prefer Chrome."),
])

jarvis.chat("open spotify and search lofi on youtube")
jarvis.chat("what's the weather in Tokyo and who won the last F1 race?")

3. Or do raw tool-calling

tools = ezos.openai_tools()           # or ezos.anthropic_tools() for Claude
resp = client.chat.completions.create(model=..., tools=tools, messages=[...])
msg = resp.choices[0].message
if msg.tool_calls:
    messages.append(msg)
    messages += ezos.handle_openai_tool_calls(msg.tool_calls)   # ezos runs them

💡 A complete, runnable chatbot is in test.py (Gemini) and jarvis_demo.py (any provider, with an offline keyword fallback that needs no API key).

🔎 Web research (no API key)

ezos.web_search("who won the match today")       # -> [{title, url, snippet}, ...]
ezos.read_webpage("https://en.wikipedia.org/wiki/Mars")   # clean text
info = ezos.research("python 3.13 new features")  # search + read top pages
print(info["summary"])                            # feed straight to your AI

👁️ Give the AI its own cursor (vision agents)

When commands aren't enough, hand a vision model its own eyes, mouse and keyboard. grid_screenshot() takes a screenshot with a labelled x,y coordinate grid drawn on top — the model reads a coordinate straight off the picture and moves its own cursor there.

cur = ezos.give_cursor()      # the AI's own mouse
kb  = ezos.give_keyboard()    # the AI's own keyboard

shot = cur.look()             # screenshot + coordinate grid -> shot["path"]
# ...show shot["path"] to GPT-4o / Gemini / Claude, it replies "click 840,460"...
cur.click(840, 460)           # click the search bar it saw
kb.type("karan aujla"); kb.press("enter")

Or let the built-in VisionAgent run the whole see → think → act loop for you:

from openai import OpenAI
import ezos

agent = ezos.VisionAgent(OpenAI(), model="gpt-4o")
agent.do("open spotify and play karan aujla")
# each step: grid screenshot -> model picks coordinates -> clicks & types -> repeat

More agent superpowers:

ezos.click_text("Sign in")          # OCR-find on-screen text and click it
ezos.read_screen()                  # OCR everything on screen to text
ezos.remember("owner", "boss")      # long-term memory (survives restarts)
ezos.recall("owner")
cmd = ezos.listen()                 # mic -> text ("play karan aujla on spotify")
ezos.api_call("https://api.github.com/repos/python/cpython")   # hit any API
ezos.run_python("import ezos; ezos.open_app('spotify')")       # AI runs its own code
job = ezos.every(60, "battery_status")    # repeat in the background; job.stop()

Vision/cursor extras are optional installs: pip install ezos[all] gets you Pillow (the grid), pyautogui, OCR (pytesseract — plus the Tesseract engine) and voice (SpeechRecognition). The mouse/keyboard still work dependency-free on Windows via a built-in ctypes fallback.

📚 The 118 commands

Open index.html in a browser for a searchable reference with an example for every function. Categories:

See everything at runtime:

ezos.help_me()            # printed overview
ezos.list_commands()      # list of names
ezos.describe_commands()  # name + params + doc (great for feeding an LLM)

🛠️ How it works

• App launching uses Get-StartApps + explorer.exe shell:AppsFolder\<AppID>, which resolves any Start-menu app (Store or desktop), not just PATH entries.
• Browser finds the real chrome.exe / msedge.exe / firefox.exe so the URL opens in the browser you ask for.
• Media keys, window control, volume use ctypes — no third-party deps.
• Web/weather use the standard-library urllib; research adds DDGS + BS4.

⚠️ Safety

• Built and tested on Windows 11. File/web helpers also work on macOS/Linux; app-launch / volume / window / wallpaper helpers are Windows-first.
• Destructive verbs (delete_file, delete_folder, shutdown, empty_recycle_bin) do exactly what they say — have your AI confirm before calling them. whatsapp_message only opens the chat; you press Send.

🤝 Contributing

Contributions are welcome! To add a command:

1. Write a function in ezos.py that returns _ok(...) / _fail(...).
2. Add a camelCase alias in the aliases block.
3. Add an entry to index.html so it shows in the docs.
4. Open a PR. 🎉

Found a bug or want a feature? Open an issue.

📄 License

Released under the MIT License — see LICENSE. Free to use, modify, and share.