heya-agent 0.0.1__tar.gz

heya_agent-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shameem Reza
+
+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.

heya_agent-0.0.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: heya-agent
+Version: 0.0.1
+Summary: A single, local-first, model-agnostic, tool-using AI agent.
+Author: Shameem Reza
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shameemreza/heya
+Project-URL: Repository, https://github.com/shameemreza/heya
+Keywords: ai,agent,cli,local-first,woocommerce,wordpress,support
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: rich>=13
+Requires-Dist: prompt_toolkit>=3
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: mcp>=1.0; extra == "test"
+Requires-Dist: trustme>=1.0; extra == "test"
+Dynamic: license-file
+
+# Heya
+
+Heya is a single, local-first AI agent that runs in your terminal. One model,
+one agent, a toolbox. It reads a request, decides what to do, calls tools, and
+loops until the task is done.
+
+The model is a configuration choice, not part of the design. The same loop runs
+against a small local model through Ollama or a frontier cloud model through
+OpenRouter, OpenAI, LM Studio, or anything that speaks the OpenAI chat API. Point
+it at whatever you have. Your prompts and your data stay on your machine.
+
+It is built in plain Python with no agent framework, so you can see exactly what
+every part does.
+
+## Why you might use it
+
+Most agents are general. Heya is general too, but it carries a real specialty: a
+WordPress and WooCommerce diagnostic assistant that takes a bug from a ticket to
+a proven answer. And because it is model-agnostic and local-first, you run all of
+that on your own models, with no vendor lock-in and nothing leaving your machine.
+
+It also hosts the Claude Code ecosystem. Your existing Claude skills, plugins,
+hooks, commands, and sub-agents work in Heya with no re-install, so you bring
+what you already have.
+
+## What it can do
+
+- **Diagnostic assistant.** Give Heya a bug report, a ticket, or a log. It
+  reproduces the issue on a disposable WordPress Playground (or a dev site),
+  finds the root cause, proposes and verifies a fix, and hands you a paste-ready
+  triage comment with a verdict, impact, suggested priority, evidence, and a
+  one-click repro link. Every stage is evidence-gated: no evidence, no verdict.
+  It can also rank a backlog into a pick-list so you know what to work on.
+- **Hosts your Claude ecosystem.** Discovers your `~/.claude` skills and plugins
+  and makes them available through a `Skill` tool, runs lifecycle hooks (off by
+  default), and turns Claude sub-agent and command definitions into Heya roles
+  and commands.
+- **Sub-agents.** Delegate a self-contained task to a fresh, context-isolated
+  child agent, or fan several read-only children out in parallel and synthesize
+  their reports.
+- **MCP client.** Connect Model Context Protocol servers over stdio or HTTP, with
+  OAuth, sampling, elicitation, and logging.
+- **Memory.** Heya remembers facts across sessions in plain markdown files you
+  can read and edit.
+- **Code review.** A deterministic gather, fan-out, adversarially-verify,
+  synthesize pipeline that reports real issues and says "nothing blocks" rather
+  than inventing findings.
+- **Cost and context controls.** An optional cheaper model for forgiving work,
+  a per-task token budget, and context compaction so long sessions keep working
+  on small-window local models.
+- **Files, shell, web, and a real browser.** All writes, shell commands, and
+  browser clicks ask before they run. Reads run on their own. Everything is
+  confined to an allow-list of folders.
+
+## Install
+
+You need Python 3.11 or newer. The package is `heya-agent`; the command is
+`heya`.
+
+```bash
+pipx install heya-agent
+```
+
+[pipx](https://pipx.pypa.io) installs it into its own isolated environment and
+puts `heya` on your PATH. If you do not have pipx, `pip install heya-agent`
+works too. Then run `heya init` to set up a model.
+
+The browser tools are optional, since they pull in Playwright and a Chromium
+binary. Add them when you want them:
+
+```bash
+pipx install "heya-agent[browser]"
+python -m playwright install chromium
+```
+
+Heya runs fine without them. The browser tools just return an install hint until
+you do.
+
+Connecting MCP servers (hosting other tools over the Model Context Protocol)
+needs the `mcp` extra:
+
+```bash
+pipx install "heya-agent[mcp]"
+```
+
+### From source (for contributors)
+
+```bash
+git clone git@github.com:shameemreza/heya.git
+cd heya
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+## Point it at a model
+
+Run the setup wizard. It walks you through a local (Ollama) or cloud model and
+writes the config for you:
+
+```bash
+heya init
+```
+
+A pasted cloud key is stored in a locked credentials file, never in the config.
+On the local path the wizard offers to download a model for you. If you would
+rather configure by hand, copy `config.example.toml` to
+`~/.config/heya/config.toml` and edit it. See
+[docs/guide/getting-started.md](docs/guide/getting-started.md).
+
+## Run it
+
+```bash
+heya "summarize what changed in the last 3 commits"
+```
+
+Triage a bug end to end:
+
+```bash
+heya "triage this: variation coupons apply to the parent price at checkout on WP 6.5 / WC 8.7"
+```
+
+Use a skill you already have:
+
+```bash
+heya "use my support-reply skill to draft a response to this ticket: ..."
+```
+
+## Docs
+
+- [Getting started](docs/guide/getting-started.md)
+- [Configuration reference](docs/guide/configuration.md)
+- [The diagnostic workflow](docs/guide/diagnostic-workflow.md)
+- [Hosting your Claude skills, plugins, and tools](docs/guide/hosting-claude-ecosystem.md)
+- [Tools and safety](docs/guide/tools-and-safety.md)
+- [Connect your own MCP servers](docs/guide/mcp.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

heya_agent-0.0.1/README.md

@@ -0,0 +1,140 @@
+# Heya
+
+Heya is a single, local-first AI agent that runs in your terminal. One model,
+one agent, a toolbox. It reads a request, decides what to do, calls tools, and
+loops until the task is done.
+
+The model is a configuration choice, not part of the design. The same loop runs
+against a small local model through Ollama or a frontier cloud model through
+OpenRouter, OpenAI, LM Studio, or anything that speaks the OpenAI chat API. Point
+it at whatever you have. Your prompts and your data stay on your machine.
+
+It is built in plain Python with no agent framework, so you can see exactly what
+every part does.
+
+## Why you might use it
+
+Most agents are general. Heya is general too, but it carries a real specialty: a
+WordPress and WooCommerce diagnostic assistant that takes a bug from a ticket to
+a proven answer. And because it is model-agnostic and local-first, you run all of
+that on your own models, with no vendor lock-in and nothing leaving your machine.
+
+It also hosts the Claude Code ecosystem. Your existing Claude skills, plugins,
+hooks, commands, and sub-agents work in Heya with no re-install, so you bring
+what you already have.
+
+## What it can do
+
+- **Diagnostic assistant.** Give Heya a bug report, a ticket, or a log. It
+  reproduces the issue on a disposable WordPress Playground (or a dev site),
+  finds the root cause, proposes and verifies a fix, and hands you a paste-ready
+  triage comment with a verdict, impact, suggested priority, evidence, and a
+  one-click repro link. Every stage is evidence-gated: no evidence, no verdict.
+  It can also rank a backlog into a pick-list so you know what to work on.
+- **Hosts your Claude ecosystem.** Discovers your `~/.claude` skills and plugins
+  and makes them available through a `Skill` tool, runs lifecycle hooks (off by
+  default), and turns Claude sub-agent and command definitions into Heya roles
+  and commands.
+- **Sub-agents.** Delegate a self-contained task to a fresh, context-isolated
+  child agent, or fan several read-only children out in parallel and synthesize
+  their reports.
+- **MCP client.** Connect Model Context Protocol servers over stdio or HTTP, with
+  OAuth, sampling, elicitation, and logging.
+- **Memory.** Heya remembers facts across sessions in plain markdown files you
+  can read and edit.
+- **Code review.** A deterministic gather, fan-out, adversarially-verify,
+  synthesize pipeline that reports real issues and says "nothing blocks" rather
+  than inventing findings.
+- **Cost and context controls.** An optional cheaper model for forgiving work,
+  a per-task token budget, and context compaction so long sessions keep working
+  on small-window local models.
+- **Files, shell, web, and a real browser.** All writes, shell commands, and
+  browser clicks ask before they run. Reads run on their own. Everything is
+  confined to an allow-list of folders.
+
+## Install
+
+You need Python 3.11 or newer. The package is `heya-agent`; the command is
+`heya`.
+
+```bash
+pipx install heya-agent
+```
+
+[pipx](https://pipx.pypa.io) installs it into its own isolated environment and
+puts `heya` on your PATH. If you do not have pipx, `pip install heya-agent`
+works too. Then run `heya init` to set up a model.
+
+The browser tools are optional, since they pull in Playwright and a Chromium
+binary. Add them when you want them:
+
+```bash
+pipx install "heya-agent[browser]"
+python -m playwright install chromium
+```
+
+Heya runs fine without them. The browser tools just return an install hint until
+you do.
+
+Connecting MCP servers (hosting other tools over the Model Context Protocol)
+needs the `mcp` extra:
+
+```bash
+pipx install "heya-agent[mcp]"
+```
+
+### From source (for contributors)
+
+```bash
+git clone git@github.com:shameemreza/heya.git
+cd heya
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+## Point it at a model
+
+Run the setup wizard. It walks you through a local (Ollama) or cloud model and
+writes the config for you:
+
+```bash
+heya init
+```
+
+A pasted cloud key is stored in a locked credentials file, never in the config.
+On the local path the wizard offers to download a model for you. If you would
+rather configure by hand, copy `config.example.toml` to
+`~/.config/heya/config.toml` and edit it. See
+[docs/guide/getting-started.md](docs/guide/getting-started.md).
+
+## Run it
+
+```bash
+heya "summarize what changed in the last 3 commits"
+```
+
+Triage a bug end to end:
+
+```bash
+heya "triage this: variation coupons apply to the parent price at checkout on WP 6.5 / WC 8.7"
+```
+
+Use a skill you already have:
+
+```bash
+heya "use my support-reply skill to draft a response to this ticket: ..."
+```
+
+## Docs
+
+- [Getting started](docs/guide/getting-started.md)
+- [Configuration reference](docs/guide/configuration.md)
+- [The diagnostic workflow](docs/guide/diagnostic-workflow.md)
+- [Hosting your Claude skills, plugins, and tools](docs/guide/hosting-claude-ecosystem.md)
+- [Tools and safety](docs/guide/tools-and-safety.md)
+- [Connect your own MCP servers](docs/guide/mcp.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

heya_agent-0.0.1/heya/__init__.py

@@ -0,0 +1,3 @@
+"""Heya — a single, local-first, tool-using AI agent."""
+
+__version__ = "0.0.1"