relio 0.1.0__tar.gz

relio-0.1.0/.gitignore

@@ -0,0 +1,171 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Pyinstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so content is dynamic.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nosenv/
+.pytest_cache/
+.mypy_cache/
+.cache/
+.ruff_cache/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or app, you might want to share your .python-version.
+#   Reference: https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-version
+#.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if lock is used, it may cause conflicts.
+#Pipfile.lock
+
+# poetry
+#   Using Poetry requires Pipfile.lock to be in version control, but it might not be if you're not using Poetry.
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#.pdm-python
+#pdm.lock
+
+# PEP 582; used by e.g. pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# IDEs
+.vscode/
+.idea/
+.claude/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.swp
+
+# Relio specific database files
+*.db
+*.sqlite
+*.sqlite3
+relio.db
+query_log.json
+
+# Node/React frontend
+node_modules/
+frontend/node_modules/
+frontend/dist/
+frontend/.env
+frontend/.env.local
+frontend/.env.development.local
+frontend/.env.test.local
+frontend/.env.production.local

relio-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to Relio
+
+Thanks for working on Relio. This guide gets you from clone to green tests and
+explains the conventions the codebase follows.
+
+## Dev setup
+
+Requires Python 3.11+.
+
+```bash
+git clone <repo> relio && cd relio
+python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest                                            # should be all green
+```
+
+`pyproject.toml` sets `pythonpath = ["."]`, so `pytest` finds the `relio`
+package without any extra setup.
+
+### Optional / gated tests
+- **Postgres** integration tests are skipped unless a database is provided:
+  ```bash
+  RELIO_TEST_DATABASE_URL=postgresql://user:pass@localhost/relio_test pytest -m integration
+  ```
+  (Needs the `vector` extension available.)
+- **Local embedding** model tests download a model; they're marked `integration`.
+
+## How the project is built
+
+Relio is developed **spec-first, test-first**:
+
+1. **Design spec** — non-trivial work starts with a short spec under
+   `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` (goal, design, tests,
+   what's out of scope).
+2. **Tests first** — write the failing tests, then the implementation.
+3. **Keep the suite green** — every change leaves `pytest` passing.
+
+The architecture is described in
+`docs/superpowers/specs/2026-06-30-relio-architecture-v2-app-first.md` — read it
+before adding a component. The short version: the app is the developer's; the AI
+engine is a **called-in component** (`RelioAI`); the DB is reached only through
+the **exposure map**; agents are **bounded contexts**.
+
+## Conventions
+
+- **One concern per module.** When a file grows large, split it.
+- **Match the surrounding code** — naming, comment density, idioms.
+- **No new network hops.** The backend↔engine call is in-process by design; keep
+  it that way unless a component genuinely must scale out behind a seam
+  (`StorageBackend`, `AuthHook`, MCP).
+- **Backends implement the full `StorageBackend` contract** (`add/get/delete/
+  search/all/query/transaction/close`); add the matching SQLite **and** Postgres
+  paths, with Postgres tests gated `integration`.
+- **Identity comes from the auth hook**, never from request bodies.
+- **Tests + docs for everything.** The framework ships a `relio check` gate that
+  enforces this on scaffolded apps; hold the framework's own code to the same bar
+  (a test for every module, a design spec for every feature).
+
+## Layout
+
+```
+relio/ai.py            # RelioAI seam
+relio/exposure.py      # exposure map (tool registry + field allowlist)
+relio/agents.py        # bounded agents
+relio/memory.py        # the engine (add/recall/history/query/graph/transaction)
+relio/backends/        # sqlite.py, postgres.py (StorageBackend)
+relio/embedding/       # base/local/cache (+ batch)
+relio/server/          # app, routes (memory/chat/graph/history), auth, llm, agent
+relio/cli/             # main, scaffold, check, dockerfile
+relio/sdkgen.py        # OpenAPI -> TS + Python SDK
+relio/templates/       # web / mobile / desktop scaffolds
+tests/                 # mirrors the package; server tests under tests/server/
+```
+
+## Pull requests
+
+- Reference or include the design spec for the change.
+- Keep PRs focused; one feature/concern per PR.
+- Run `pytest` (and `pytest -m integration` if you touched Postgres paths).
+- Update the relevant doc/spec in the same PR.

relio-0.1.0/LICENSE

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

relio-0.1.0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: relio
+Version: 0.1.0
+Summary: Relio — app-first AI framework with a built-in, governed memory engine
+Author-email: Sujith Krishnan <sujith.krishnan@techjays.com>
+License: MIT License
+        
+        Copyright (c) 2026 Relio 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.
+License-File: LICENSE
+Keywords: agents,ai,fastapi,framework,llm,mcp,memory,pgvector,rag,react,vector
+Classifier: Development Status :: 3 - Alpha
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Requires-Dist: sqlite-vec>=0.1.6
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.40; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: fastembed>=0.3; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mcp>=1.2; extra == 'dev'
+Requires-Dist: pydantic-settings>=2.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: fastembed>=0.3; extra == 'local'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: psycopg-pool>=3.2; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: server
+Requires-Dist: anthropic>=0.40; extra == 'server'
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: pydantic-settings>=2.2; extra == 'server'
+Requires-Dist: uvicorn>=0.30; extra == 'server'
+Description-Content-Type: text/markdown
+
+# Relio
+
+**An app-first AI framework.** Build a normal FastAPI + React app with your own
+data, and *call AI in* where you need it — memory, retrieval, agents, document
+extraction, and MCP — as one in-process component, not a pile of services.
+
+> Relio is **memory-native**: vectors + graph + structured query live in one
+> SQLite file (or Postgres), and the AI reaches your app's data only through a
+> governed, field-limited **exposure map**.
+
+- **One seamless system** — backend calls the AI in-process (no network hop), one
+  port, one deploy.
+- **AI is a component, not the product** — the `RelioAI` seam is LLM-optional;
+  use just `recall`, or the whole stack (chat, agents, extraction, MCP).
+- **Governed by default** — the AI sees only what you declare; agents are bounded
+  contexts with their own memory + tools.
+- **Batteries for building** — scaffolds (web/mobile/desktop), generated SDKs, and
+  a dev harness that won't let code land without a test and a doc.
+
+> Status: early / pre-release (`0.1.0`). The engine, server, SDKs, agents,
+> extraction, and CLI are tested. Postgres paths and the vision/extraction model
+> call are integration-gated (need a live DB / API). See [Status](#status).
+
+---
+
+## Install
+
+Requires **Python 3.11+** (and Node 18+ only if you scaffold a web/mobile/desktop
+client).
+
+> **Not on PyPI yet** (pre-release `0.1.0`) — install from source.
+
+Clone and install editable:
+
+```bash
+git clone <repo> relio
+cd relio
+pip install -e ".[server]"       # or ".[dev]" for the full toolchain + tests
+```
+
+…or install straight from a local checkout without `cd`-ing into it (note the
+quotes — the brackets are part of the requirement):
+
+```bash
+pip install -e "C:/path/to/relio[server]"
+```
+
+Once it's published, this will be:
+
+```bash
+pip install "relio[server]"
+```
+
+Optional extras (combine, e.g. `.[server,postgres]`):
+
+| Extra | Adds |
+|-------|------|
+| `local` | local ONNX embeddings (`fastembed`) — zero-API-cost vectors |
+| `mcp` | the MCP server |
+| `postgres` | Postgres + pgvector backend (with connection pooling) |
+| `server` | FastAPI, uvicorn, Anthropic SDK |
+| `dev` | everything + pytest/coverage |
+
+Verify and run the tests:
+
+```bash
+relio --help
+pytest            # 150+ tests (from a source clone)
+```
+
+---
+
+## Quickstart (use the AI component)
+
+```python
+from relio import RelioAI
+
+ai = RelioAI(path="relio.db")          # local SQLite + local embeddings, no LLM needed
+ai.remember("Alice manages the Acme account")
+print(ai.recall("who manages Acme?")[0].content)   # -> "Alice manages the Acme account"
+```
+
+Add an LLM when you want chat/extraction (set `ANTHROPIC_API_KEY`):
+
+```python
+from relio import RelioAI
+from relio.server.llm.claude import ClaudeProvider
+
+ai = RelioAI(path="relio.db", provider=ClaudeProvider())
+for chunk in ai.chat("what do you know about Acme?"):
+    print(chunk, end="")
+```
+
+## Scaffold a full app
+
+```bash
+relio new myapp --web      # FastAPI backend + React (Vite) frontend + generated SDK
+cd myapp
+relio dev                  # backend + Vite dev server on one URL
+```
+
+`relio new` also supports `--mobile` (Expo) and `--desktop` (Tauri), all on the
+same generated TypeScript SDK.
+
+---
+
+## Core concepts
+
+### The `RelioAI` seam — the called-in component
+One object composing the AI-system components. The LLM is optional.
+
+```python
+ai.remember(text, scope=...)        # store          ai.recall(query)        # semantic retrieval
+ai.embed(["a", "b"])                # batch embeddings ai.query(type=..., where=...)  # structured filter
+ai.add_node / add_edge / neighbors / traverse          # knowledge graph
+ai.chat(message)                    # agent loop (needs a provider)
+ai.extract / ai.extract_file        # structured / multimodal extraction
+ai.mcp_server()                     # expose to external agents over MCP
+```
+
+### Exposure map — governed access to *your* data
+Your app DB is private. The AI can call only what you declare, and see only the
+fields you allow.
+
+```python
+@ai.tool
+def lookup_account(name: str) -> dict:
+    row = db.get_account(name)
+    return ai.expose(row, fields=["name", "owner", "status"])   # cost/PII stay invisible
+
+ai.call_tool("lookup_account", name="Acme")
+# the same map auto-publishes as MCP tools: ai.mcp_server(include_tools=True)
+```
+
+### Agents — bounded contexts
+Each agent gets its own memory namespace, tool slice, config, and session.
+Private by default.
+
+```python
+billing = ai.agent("billing", tools=["lookup_account"], system="You handle billing.")
+billing.remember("invoice 42 overdue")     # not visible to other agents
+billing.call_tool("refund", ...)           # PermissionError — not in its slice
+```
+
+### Document extraction (AI beyond chat)
+```python
+bom = ai.extract_file("drawing.pdf", schema={"properties": {"part_no": {}, "qty": {}}})
+```
+
+### Run it as a server
+```python
+from relio import Memory
+from relio.server import create_app
+from relio.server.llm.claude import ClaudeProvider
+
+app = create_app(Memory(path="relio.db"), ClaudeProvider())   # uvicorn app:app
+# memory-only backend (no LLM):  create_app(Memory())
+```
+
+Endpoints: `POST /api/chat` (SSE), `/api/memory` CRUD + `/search` + `/query`,
+`/api/history`, `/api/graph/neighbors`, `/api/health`. Identity comes from an
+**auth hook** (`anonymous_auth` default, or `ApiKeyAuth`), never from the request
+body — so tenants are isolated by construction.
+
+---
+
+## CLI
+
+| Command | Does |
+|---------|------|
+| `relio new <name> [--web/--mobile/--desktop]` | scaffold an app (+ generated SDK + dev harness) |
+| `relio dev` | run backend + frontend dev servers on one URL |
+| `relio build` | build the React frontend |
+| `relio serve [--port]` | serve API + built frontend on one port |
+| `relio sdk [--out]` | generate the TS + Python SDKs from the API |
+| `relio develop ["<task>"]` | drive the Claude Code CLI to build a feature (feeds gate gaps to it) |
+| `relio test [--coverage --min N]` | run the test suites (optionally enforce coverage) |
+| `relio check` | **governance gate** — fail if any module lacks a test and a doc |
+| `relio dockerfile` / `relio deploy` | production Dockerfile / build image |
+
+### The governance gate
+A scaffolded app ships a `CLAUDE.md` (conventions), `docs/`, `tests/`, and a
+`.claude/` Stop hook that runs `relio check`. The gate requires **every module
+(Python and TypeScript) to have a test and a doc** — and a fresh scaffold passes
+it out of the box. So agentic development with `relio develop` can't end with
+undocumented or untested code.
+
+---
+
+## Backends & config
+
+- **Default:** one SQLite file (vectors via `sqlite-vec`, WAL, indexed structured
+  query). Backups = copy the file.
+- **Scale:** `Memory(database_url="postgresql://…")` swaps to **Postgres +
+  pgvector** (JSONB + GIN, connection pooling) — no caller changes.
+- **Server config** via `RELIO_*` env (`RELIO_DATABASE_URL`, `RELIO_MODEL`, …).
+
+---
+
+## Project layout
+
+```
+relio/            # the framework package
+  ai.py           # RelioAI seam            exposure.py  # exposure map
+  agents.py       # bounded agents          memory.py    # the engine
+  backends/       # sqlite, postgres        embedding/   # local + cache + batch
+  server/         # FastAPI app, routes, auth, llm providers, agent loop
+  cli/            # new/dev/serve/sdk/develop/test/check
+  templates/      # web (React), mobile (Expo), desktop (Tauri)
+docs/superpowers/specs/   # design specs (architecture v2 + every feature)
+tests/            # 150+ tests
+```
+
+Start with [`docs/superpowers/specs/2026-06-30-relio-architecture-v2-app-first.md`](docs/superpowers/specs/2026-06-30-relio-architecture-v2-app-first.md)
+for the full architecture.
+
+---
+
+## Status
+
+| Area | State |
+|------|-------|
+| Engine, server, auth, graph, query, agents, SDK gen, scaffolds, CLI, dev harness | ✅ tested |
+| Postgres + pgvector (backend, pooling, JSONB) | ⚙️ implemented; integration-gated (`RELIO_TEST_DATABASE_URL`, `pytest -m integration`) |
+| Claude vision/extraction call | ⚙️ implemented; untested without an API key (the offline fake path is tested) |
+| Generated TS SDK / mobile / desktop apps | ⚙️ scaffolded + structurally tested; not compiled in CI |
+
+---
+
+## License
+
+Intended **open-core**: the framework is MIT (see [LICENSE](LICENSE)); a future
+managed cloud + enterprise components are separately licensed. See the project's
+licensing notes.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). In short: tests-first, every change keeps
+the suite green, and design specs live under `docs/superpowers/specs/`.