Metadata-Version: 2.4
Name: openyfai-aria
Version: 1.0.1
Summary: Local-first AI agent with memory, knowledge graph, tools, web dashboard, and Telegram (OpenYF AI).
Author: Youel
Maintainer: OpenYF AI
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/openyfai/aria
Project-URL: Repository, https://github.com/openyfai/aria
Project-URL: Issues, https://github.com/openyfai/aria/issues
Project-URL: Changelog, https://github.com/openyfai/aria/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/openyfai/aria#readme
Keywords: ai-agent,local-first,knowledge-graph,llm,autonomy,telegram,tools,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: aiofiles>=24.0
Requires-Dist: networkx>=3.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: openai>=1.79.0
Requires-Dist: anthropic>=0.52.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Provides-Extra: web
Requires-Dist: fastapi>=0.111; extra == "web"
Requires-Dist: uvicorn>=0.30; extra == "web"
Provides-Extra: browser
Requires-Dist: playwright>=1.45; extra == "browser"
Requires-Dist: playwright-stealth>=1.0; extra == "browser"
Requires-Dist: html2text>=2024.2.26; extra == "browser"
Provides-Extra: vector
Requires-Dist: chromadb>=0.5; extra == "vector"
Provides-Extra: local
Requires-Dist: httpx>=0.27; extra == "local"
Provides-Extra: providers
Requires-Dist: openai>=1.79.0; extra == "providers"
Requires-Dist: anthropic>=0.52.0; extra == "providers"
Provides-Extra: full
Requires-Dist: fastapi>=0.111; extra == "full"
Requires-Dist: uvicorn>=0.30; extra == "full"
Requires-Dist: playwright>=1.45; extra == "full"
Requires-Dist: playwright-stealth>=1.0; extra == "full"
Requires-Dist: html2text>=2024.2.26; extra == "full"
Requires-Dist: chromadb>=0.5; extra == "full"
Requires-Dist: docker>=7.0; extra == "full"
Requires-Dist: httpx>=0.27; extra == "full"
Requires-Dist: openai>=1.79.0; extra == "full"
Requires-Dist: anthropic>=0.52.0; extra == "full"
Dynamic: license-file

# ARIA (Bringing AGI to the Public)

**What this is:** ARIA is an **experimental, local-first AI agent** from **[OpenYF AI](https://github.com/openyfai)**. It combines chat with **persistent memory**, a living **knowledge graph**, governed **tools**, an optional **web dashboard**, and **Telegram** integration. Sources and updates live at **[github.com/openyfai/aria](https://github.com/openyfai/aria)**.

**Who it's for:** people who want **more than a raw chat completion** — operators who configure providers, approvals, identity, and (optionally) 24/7 proactive behavior behind clear safety defaults.

We are building in public; you can adopt it as-is, customize skills, or follow the codebase as the project evolves.

---

**In one sentence:** install once, run **`aria setup`** or open the dashboard with **`aria web`**, optionally pair Telegram, and chat.

## Quick start (PyPI — recommended)

You need **Python 3.11 or newer** (latest stable 3.x is recommended).

```bash
pip install "openyfai-aria[full]"
```

**Option A — browser setup (default):**

```bash
aria web
```

Open **[http://127.0.0.1:8000](http://127.0.0.1:8000)**, complete provider and safety settings in the UI, then use Chat (and Graph / Operator / Settings as you like).

**Option B — terminal setup only:**

```bash
aria setup
```

Then run **`aria`** for the terminal agent or **`aria web`** for the dashboard.

**Optional:** background daemon (non-Windows / see notes in CLI): **`aria start`**

PyPI wheels include a **pre-built dashboard** when published through the project’s release workflow; you should **not** need Node or `npm` for a normal install.

Try a first prompt such as: *Analyze this repo and build a knowledge graph of the architecture.*

More detail: [`docs/quickstart.md`](docs/quickstart.md).

## Developing from source (contributors)

Clone the repo and use an editable install when you are changing Python or the Next.js UI:

```bash
git clone https://github.com/openyfai/aria.git && cd aria
pip install -e ".[full,dev]"
```

If you change the **web frontend**, build it once so `aria web` can serve `aria-ui/out` from your checkout:

```bash
cd aria-ui && npm install && npm run build && cd ..
```

Release builds (CI) copy this output into `aria/web_dist/` for **PyPI** wheels — see [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Why ARIA

- Local-first memory and state backed by SQLite.
- A visible graph of what the agent believes.
- Provider and model choice from the setup wizard or `aria setup`.
- Operator controls for approvals, usage, Telegram pairing, and remote access.
- Markdown skills that let contributors extend behavior without editing Python.

## More ways to run

| Path | When to use |
|------|-------------|
| **Web UI** (`aria web`) | Default: finish setup in the browser. |
| **Terminal agent** (`aria` after setup) | Keyboard-first use. |
| **CLI setup only** (`aria setup`) | You prefer not to use the web wizard once. |
| **Docker** | Deploy to a server or share on a LAN; needs `.env` and a web API key. See [`docs/quickstart.md`](docs/quickstart.md#deploy--server-docker). |

## Requirements

- **Python** `>=3.11` (matches package metadata on PyPI).
- **Node 20+** — only if you develop or rebuild `aria-ui/` from source (not required for standard `pip install` wheels).
- **Docker** — optional.

## Safe defaults

- Tool approvals are on.
- Terminal execution is off.
- Direct code writes are off.
- Background actions are off.
- Remote web binds require `ARIA_WEB_API_KEY`.
- Telegram is deny-by-default until paired from **Operator**.

Read [`SECURITY.md`](SECURITY.md) before exposing ARIA beyond localhost.

## Power user / troubleshooting

If chat or setup fails after you have saved provider keys, see [`docs/quickstart.md`](docs/quickstart.md#power-user--troubleshooting-commands) for `aria doctor`, `aria doctor --ping`, and related commands. You do not need these for a first successful run.

## Provider support

Gemini, OpenAI, Anthropic, OpenRouter, DeepSeek, Mistral, Groq, Ollama, and local OpenAI-compatible endpoints. Settings come from the wizard, `aria setup`, `data/` runtime files, or environment variables.

## Skills

Add a Markdown file under `skills/`, restart ARIA, and the agent can use that workflow. Start with [`skills/repo_researcher.md`](skills/repo_researcher.md) or [`skills/README.md`](skills/README.md).

## Repository guide

- Core loop: `aria/core/cognitive_loop.py`
- Providers: `aria/llm/`
- Web backend: `scripts/web_server.py`
- CLI: `scripts/cli.py`
- Telegram: `scripts/telegram_bot.py`
- Web UI: `aria-ui/src/`
- Packaged static UI (release builds): `aria/web_dist/`
- Skills: `skills/`

## Development

```bash
python -m pytest tests
ruff check .
cd aria-ui && npm install && npm run lint && npm run build
```

## Project docs

- [`docs/quickstart.md`](docs/quickstart.md) — install paths, Docker, troubleshooting  
- [`CONTRIBUTING.md`](CONTRIBUTING.md)  
- [`SECURITY.md`](SECURITY.md)  
- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)  
- [`docs/planning/ROADMAP.md`](docs/planning/ROADMAP.md) — phased roadmap  
- [`docs/planning/launch-checklist.md`](docs/planning/launch-checklist.md) — pre-public-release checklist  
- [`docs/planning/launch-issue-backlog.md`](docs/planning/launch-issue-backlog.md) — seeded “good first issue” ideas  
- [`CHANGELOG.md`](CHANGELOG.md)

## License

Apache-2.0. See [`LICENSE`](LICENSE).
