tiles-ai 0.1.0__tar.gz

tiles_ai-0.1.0/LICENSE

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

tiles_ai-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: tiles-ai
+Version: 0.1.0
+Summary: Tiles AI — a phone-home-screen control plane for AI agents. Register, activate, observe, and permission tiles.
+Author-email: Manav Singhai <manavsinghai11@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Manav020201/tiles-ai
+Project-URL: Repository, https://github.com/Manav020201/tiles-ai
+Project-URL: Issues, https://github.com/Manav020201/tiles-ai/issues
+Keywords: ai,agents,llm,mcp,control-plane,fastapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.27
+Requires-Dist: watchfiles>=0.21
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# 🟩 Tiles AI
+
+**A home screen for your AI agents.** Lay your agents out as tiles on a board,
+tap one to run it, and stay in control of anything it does.
+
+[![CI](https://github.com/Manav020201/tiles-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/Manav020201/tiles-ai/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+![Tiles AI — a home screen for your AI agents](docs/hero.svg)
+
+## What is it?
+
+Think of your phone's home screen — but every app is an AI agent.
+
+- A **board** is a grid of **tiles**.
+- Each **tile** is one agent that does a single job — *"summarize my inbox"*,
+  *"tidy this folder"*, *"draft a reply"*.
+- Tap a tile and it turns **green** — running.
+
+Tiles AI handles the parts *around* an agent — running it, watching it, asking
+your permission before it acts, and connecting it to your apps. You bring the
+agent's logic (plain Python, or wrap LangChain / CrewAI / the OpenAI SDK).
+
+It's built for **developers learning to build agents**: start from a ready-made
+board and add your own tiles right from the screen.
+
+## Quick start
+
+You'll need **Python 3.11+** and **Node 18+** (to build the board once).
+
+```bash
+git clone https://github.com/Manav020201/tiles-ai && cd tiles-ai
+pip install -e ".[dev]"
+npm --prefix frontend install && npm --prefix frontend run build
+tiles up --echo
+```
+
+Open **http://127.0.0.1:8000** — you'll see a starter board running on a free
+offline brain (no API key needed). When you're ready for a real model, run
+`tiles up` and connect a brain from the screen.
+
+> _PyPI packaging is ready; once published this becomes `pipx install tiles-ai && tiles up`._
+
+## What you can do
+
+**Right away — no API keys:**
+
+- **Instant tiles** — Ask, Summarize, Translate, Extract, Brainstorm.
+- **Your files** — summarize a folder, find files, or tidy a folder (it *proposes*
+  the moves; you approve them).
+
+**Add your apps** — GitHub, Slack, web search, Gmail, and anything with an
+[MCP](https://modelcontextprotocol.io) server (local or remote), via an API token
+or OAuth.
+
+**All from the board — no editor required:**
+
+| | |
+|---|---|
+| ➕ **Create a tile** | fill a form; Tiles writes the files for you |
+| 🔌 **Connect an app** | paste its command; Tiles reads its tools automatically |
+| 🧠 **Choose your model** | cloud (Anthropic / OpenAI) or local (Ollama) |
+| ✅ **Approve before it acts** | anything that writes or sends waits for your OK |
+| ⏱ **Schedule & chain** | run a tile on a timer, or feed one tile's output into another |
+| 👀 **Observe** | live activity per tile, and clear errors as you go |
+
+## How it works
+
+Three ideas:
+
+| Concept | What it is |
+|---|---|
+| **Tile** | an agent — a model + instructions + a permission level. The thing you tap. |
+| **Connector** | a reusable connection to one app (e.g. GitHub). Many tiles can share it. |
+| **Brain** | the model that powers tiles. Set one once; a tile can pin its own. |
+
+**Permissions are built in.** Every tile has a level: **read-only** (never acts),
+**draft** (proposes actions you approve), or **autonomous**. Green means
+*running*, not *unsupervised*.
+
+<details>
+<summary>Architecture (for the curious)</summary>
+
+```
+React board ──HTTP/SSE──▶ FastAPI ──▶ runtime ──▶ permission gate ──▶ connector ──▶ app
+                                         └──▶ model adapter ──▶ brain (cloud / local)
+```
+
+Connectors talk to apps over [MCP](https://modelcontextprotocol.io) (stdio or
+HTTP). The full design is in [SPEC.md](SPEC.md).
+</details>
+
+## Make your own tile
+
+The easy way: click **➕ New tile** on the board, fill the form, and open the
+generated `handler.py` to customize.
+
+In code, a tile is a small folder with a manifest and one method:
+
+```python
+from tiles_ai.contracts import ActionPlan, Tile
+
+class MyTile(Tile):
+    async def run(self, input, context) -> ActionPlan:
+        answer = await context.model.complete(str(input))
+        return ActionPlan(result=answer)
+```
+
+Full guide, including how to connect a new app: **[docs/AUTHORING.md](docs/AUTHORING.md)**.
+
+## Docs
+
+- **[SPEC.md](SPEC.md)** — the design and the tile contract
+- **[docs/AUTHORING.md](docs/AUTHORING.md)** — build a tile or a connector
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — dev setup and how to help
+- **[CHANGELOG.md](CHANGELOG.md)** — what's new
+
+## Status
+
+Active development; well-tested with CI on Python 3.11 and 3.12.
+
+**Already here:** tiles **chain** (sequential flows), run on an **interval
+schedule**, and connect via **OAuth** (authorization-code) or API keys.
+
+**Refinements still to come:** branching / fan-out flows (only linear chains
+today) · cron and event triggers (only intervals today) · automatic OAuth token
+refresh. Out of scope for now: hosting and multi-user.
+
+## License
+
+[MIT](LICENSE).

tiles_ai-0.1.0/README.md

@@ -0,0 +1,131 @@
+# 🟩 Tiles AI
+
+**A home screen for your AI agents.** Lay your agents out as tiles on a board,
+tap one to run it, and stay in control of anything it does.
+
+[![CI](https://github.com/Manav020201/tiles-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/Manav020201/tiles-ai/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+![Tiles AI — a home screen for your AI agents](docs/hero.svg)
+
+## What is it?
+
+Think of your phone's home screen — but every app is an AI agent.
+
+- A **board** is a grid of **tiles**.
+- Each **tile** is one agent that does a single job — *"summarize my inbox"*,
+  *"tidy this folder"*, *"draft a reply"*.
+- Tap a tile and it turns **green** — running.
+
+Tiles AI handles the parts *around* an agent — running it, watching it, asking
+your permission before it acts, and connecting it to your apps. You bring the
+agent's logic (plain Python, or wrap LangChain / CrewAI / the OpenAI SDK).
+
+It's built for **developers learning to build agents**: start from a ready-made
+board and add your own tiles right from the screen.
+
+## Quick start
+
+You'll need **Python 3.11+** and **Node 18+** (to build the board once).
+
+```bash
+git clone https://github.com/Manav020201/tiles-ai && cd tiles-ai
+pip install -e ".[dev]"
+npm --prefix frontend install && npm --prefix frontend run build
+tiles up --echo
+```
+
+Open **http://127.0.0.1:8000** — you'll see a starter board running on a free
+offline brain (no API key needed). When you're ready for a real model, run
+`tiles up` and connect a brain from the screen.
+
+> _PyPI packaging is ready; once published this becomes `pipx install tiles-ai && tiles up`._
+
+## What you can do
+
+**Right away — no API keys:**
+
+- **Instant tiles** — Ask, Summarize, Translate, Extract, Brainstorm.
+- **Your files** — summarize a folder, find files, or tidy a folder (it *proposes*
+  the moves; you approve them).
+
+**Add your apps** — GitHub, Slack, web search, Gmail, and anything with an
+[MCP](https://modelcontextprotocol.io) server (local or remote), via an API token
+or OAuth.
+
+**All from the board — no editor required:**
+
+| | |
+|---|---|
+| ➕ **Create a tile** | fill a form; Tiles writes the files for you |
+| 🔌 **Connect an app** | paste its command; Tiles reads its tools automatically |
+| 🧠 **Choose your model** | cloud (Anthropic / OpenAI) or local (Ollama) |
+| ✅ **Approve before it acts** | anything that writes or sends waits for your OK |
+| ⏱ **Schedule & chain** | run a tile on a timer, or feed one tile's output into another |
+| 👀 **Observe** | live activity per tile, and clear errors as you go |
+
+## How it works
+
+Three ideas:
+
+| Concept | What it is |
+|---|---|
+| **Tile** | an agent — a model + instructions + a permission level. The thing you tap. |
+| **Connector** | a reusable connection to one app (e.g. GitHub). Many tiles can share it. |
+| **Brain** | the model that powers tiles. Set one once; a tile can pin its own. |
+
+**Permissions are built in.** Every tile has a level: **read-only** (never acts),
+**draft** (proposes actions you approve), or **autonomous**. Green means
+*running*, not *unsupervised*.
+
+<details>
+<summary>Architecture (for the curious)</summary>
+
+```
+React board ──HTTP/SSE──▶ FastAPI ──▶ runtime ──▶ permission gate ──▶ connector ──▶ app
+                                         └──▶ model adapter ──▶ brain (cloud / local)
+```
+
+Connectors talk to apps over [MCP](https://modelcontextprotocol.io) (stdio or
+HTTP). The full design is in [SPEC.md](SPEC.md).
+</details>
+
+## Make your own tile
+
+The easy way: click **➕ New tile** on the board, fill the form, and open the
+generated `handler.py` to customize.
+
+In code, a tile is a small folder with a manifest and one method:
+
+```python
+from tiles_ai.contracts import ActionPlan, Tile
+
+class MyTile(Tile):
+    async def run(self, input, context) -> ActionPlan:
+        answer = await context.model.complete(str(input))
+        return ActionPlan(result=answer)
+```
+
+Full guide, including how to connect a new app: **[docs/AUTHORING.md](docs/AUTHORING.md)**.
+
+## Docs
+
+- **[SPEC.md](SPEC.md)** — the design and the tile contract
+- **[docs/AUTHORING.md](docs/AUTHORING.md)** — build a tile or a connector
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — dev setup and how to help
+- **[CHANGELOG.md](CHANGELOG.md)** — what's new
+
+## Status
+
+Active development; well-tested with CI on Python 3.11 and 3.12.
+
+**Already here:** tiles **chain** (sequential flows), run on an **interval
+schedule**, and connect via **OAuth** (authorization-code) or API keys.
+
+**Refinements still to come:** branching / fan-out flows (only linear chains
+today) · cron and event triggers (only intervals today) · automatic OAuth token
+refresh. Out of scope for now: hosting and multi-user.
+
+## License
+
+[MIT](LICENSE).

tiles_ai-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tiles-ai"
+version = "0.1.0"
+description = "Tiles AI — a phone-home-screen control plane for AI agents. Register, activate, observe, and permission tiles."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Manav Singhai", email = "manavsinghai11@gmail.com" }]
+keywords = ["ai", "agents", "llm", "mcp", "control-plane", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "pydantic>=2.6",
+    "pyyaml>=6.0",
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+    "watchfiles>=0.21",  # enables `tiles up --reload` to watch *.yaml manifests too
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "httpx>=0.27",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+tiles = "tiles_ai.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Manav020201/tiles-ai"
+Repository = "https://github.com/Manav020201/tiles-ai"
+Issues = "https://github.com/Manav020201/tiles-ai/issues"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = [
+    "E501",   # line length — left to the author
+    "B008",   # FastAPI Depends-in-defaults pattern
+    "UP042",  # keep the intentional (str, Enum) mixin over StrEnum
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# py.typed ships type info (PEP 561). web/** is the built board, bundled into the
+# wheel by the release build (see RELEASING.md).
+tiles_ai = ["py.typed", "web/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

tiles_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tiles_ai-0.1.0/src/tiles_ai/__init__.py

@@ -0,0 +1,7 @@
+"""Tiles AI — a phone-home-screen control plane for AI agents.
+
+A board is a grid of tiles; each tile is an agent. Register → activate → observe
+→ permission → (later) compose. See `tiles_ai.contracts` and SPEC.md.
+"""
+
+__version__ = "0.1.0"

tiles_ai-0.1.0/src/tiles_ai/api/__init__.py

@@ -0,0 +1,11 @@
+"""The HTTP control-plane API (FastAPI) + SSE event stream.
+
+`create_app(root=..., brain_store=..., model_adapter=...)` returns a FastAPI app
+wired to a board. See SPEC.md "Build order" phase 4.
+"""
+
+from __future__ import annotations
+
+from .app import create_app, format_sse
+
+__all__ = ["create_app", "format_sse"]

tiles_ai-0.1.0/src/tiles_ai/api/__main__.py

@@ -0,0 +1,47 @@
+"""Run the Tiles AI API: `python -m tiles_ai.api`.
+
+Discovers connectors/tiles from TILES_ROOT (default: cwd) and loads the brain
+store from TILES_BRAIN (default: brain.local.yaml). The brain store is created
+empty if the file is absent — the onboarding flow writes it.
+"""
+
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+from ..contracts import HostedProvider
+from ..model import BrainStore, ModelAdapter, echo_client_factory
+from .app import create_app
+
+
+def main() -> None:
+    root = os.environ.get("TILES_ROOT", ".")
+
+    if os.environ.get("TILES_ECHO"):
+        # Zero-setup demo: an offline echo brain so the whole board works without
+        # keys or a network. Great for a first look and for contributors.
+        store = BrainStore()
+        store.add_provider(
+            HostedProvider(
+                id="demo", provider="anthropic", api_key="demo", model="claude-opus-4-8"
+            ),
+            make_default=True,
+        )
+        adapter = ModelAdapter(store, client_factory=echo_client_factory)
+        app = create_app(root=root, brain_store=store, model_adapter=adapter)
+    else:
+        brain_path = os.environ.get("TILES_BRAIN", "brain.local.yaml")
+        store = BrainStore.load(brain_path)
+        app = create_app(root=root, brain_store=store)
+
+    uvicorn.run(
+        app,
+        host=os.environ.get("TILES_HOST", "127.0.0.1"),
+        port=int(os.environ.get("TILES_PORT", "8000")),
+    )
+
+
+if __name__ == "__main__":
+    main()