Metadata-Version: 2.1
Name: actingweb
Version: 3.12.0
Summary: The official ActingWeb library
Home-page: http://actingweb.org
License: BSD
Keywords: actingweb,distributed,microservices,rest,api
Author: Greger Wedel
Author-email: support@actingweb.io
Maintainer: Greger Wedel
Maintainer-email: support@actingweb.io
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Provides-Extra: all
Provides-Extra: fastapi
Provides-Extra: flask
Provides-Extra: postgresql
Requires-Dist: alembic (>=1.13,<2.0) ; extra == "postgresql" or extra == "all"
Requires-Dist: boto3 (>=1.26)
Requires-Dist: cryptography (>=48.0.1)
Requires-Dist: fastapi (>=0.112) ; extra == "fastapi" or extra == "all"
Requires-Dist: flask (>=3.0) ; extra == "flask" or extra == "all"
Requires-Dist: httpx (>=0.28,<0.29)
Requires-Dist: jinja2 (>=3.0) ; extra == "flask" or extra == "fastapi" or extra == "all"
Requires-Dist: oauthlib (>=3.2.2)
Requires-Dist: psycopg[binary,pool] (>=3.1,<4.0) ; extra == "postgresql" or extra == "all"
Requires-Dist: pydantic (>=2.0,<3.0) ; extra == "fastapi" or extra == "all"
Requires-Dist: pyjwt[crypto] (>=2.13,<3.0)
Requires-Dist: pynamodb (>=6.0,<7.0)
Requires-Dist: requests (>=2.32.4)
Requires-Dist: sqlalchemy (>=2.0,<3.0) ; extra == "postgresql" or extra == "all"
Requires-Dist: typing-extensions (>=4.0)
Requires-Dist: uvicorn (>=0.20) ; extra == "fastapi" or extra == "all"
Requires-Dist: werkzeug (>=3.0) ; extra == "flask" or extra == "all"
Project-URL: Documentation, http://actingweb.readthedocs.io
Project-URL: Repository, https://github.com/actingweb/actingweb
Description-Content-Type: text/x-rst
====================================================================
ActingWeb — a Python framework for AI-ready, per-user micro-services
====================================================================
.. image:: https://github.com/actingweb/actingweb/actions/workflows/tests.yml/badge.svg
:target: https://github.com/actingweb/actingweb/actions/workflows/tests.yml
:alt: Tests
.. image:: https://codecov.io/gh/actingweb/actingweb/branch/master/graph/badge.svg
:target: https://codecov.io/gh/actingweb/actingweb
:alt: Coverage
.. image:: https://img.shields.io/pypi/v/actingweb.svg
:target: https://pypi.org/project/actingweb/
:alt: PyPI
.. image:: https://readthedocs.org/projects/actingweb/badge/?version=latest
:target: https://actingweb.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
**ActingWeb** is a Python framework for building secure, per-user services where
each user gets their own isolated instance — an *actor* — with a unique URL, its
own data, and its own set of relationships. It is the reference implementation of
the `ActingWeb REST protocol `_ for
distributed micro-services, and it has grown into a full application framework for
shipping the same backend to three kinds of clients at once:
- **AI clients** over the `Model Context Protocol (MCP) `_ —
expose per-user tools, prompts, and resources to ChatGPT, Claude, and other LLM
hosts, with OAuth2 authentication and per-user data isolation built in.
- **Web apps** — a built-in server-rendered Web UI for simple deployments, or a
first-class **SPA mode** with a hardened token/refresh-token session flow for
React/Vue/Svelte front-ends.
- **Native mobile apps** — iOS, Android, and Capacitor apps sign in with Apple,
Google, or GitHub using native OAuth flows (RFC 8252 code exchange, RFC 7523
JWT-bearer, and single-use deep-link tickets).
The same actor, the same properties, and the same trust and permission model back
all three. You write your business logic once as hooks and it is reachable from an
LLM tool call, a browser, a mobile app, or another ActingWeb service over REST.
Why ActingWeb?
--------------
ActingWeb is well suited to applications where **each individual user's data needs
a high degree of security and privacy** *and* a high degree of controlled
interaction with the outside world — personal AI assistants and memory services,
IoT "things" that act on a user's behalf, and bot-to-bot / service-to-service
data sharing where the user stays in control of who sees what.
Its defining constraint is that there is no way to query across users. Getting
``xyz``'s data is a request to ``/{xyz}/...``; there is no endpoint that returns
``xyz`` and ``yyz`` together. Sharing between users happens **only** through
explicit, per-user trust relationships and the standardized ActingWeb REST
protocol. This makes accidental data leakage structurally hard and makes granular,
revocable sharing the default rather than an afterthought.
Out of the box you get:
- A REST **actor** representing one user's thing, service, or agent.
- **Properties** — granular, per-actor key/value (and nested/list) storage exposed
over REST with per-property access hooks.
- A **trust** system for per-user relationships with fine-grained permissions.
- A **subscription** system so one actor can subscribe to another actor's changes.
- **OAuth2 authentication** (Google, GitHub, Apple) for both humans and AI clients.
- **MCP**, **Web UI / SPA**, and **native-mobile** front-ends over one backend.
- Pluggable persistence: **DynamoDB** (serverless) or **PostgreSQL** (SQL).
Quick example
-------------
.. code-block:: python
from actingweb.interface import ActingWebApp, ActorInterface
from actingweb.mcp import mcp_tool
app = (
ActingWebApp(
aw_type="urn:actingweb:example.com:myapp",
database="dynamodb", # or "postgresql"
fqdn="myapp.example.com",
)
.with_oauth(client_id="...", client_secret="...") # Google by default
.with_web_ui(enable=True) # server-rendered UI (False for pure SPA)
.with_mcp(enable=True, server_name="myapp") # AI clients over /mcp
)
# Lifecycle hook: initialize each new actor
@app.lifecycle_hook("actor_created")
def on_actor_created(actor: ActorInterface, **kwargs):
actor.properties.email = actor.creator
# Per-property access control
@app.property_hook("email")
def handle_email(actor, operation, value, path):
if operation == "get":
return None # hide email from external reads
return value
# An MCP tool — the same callable is reachable at GET/POST //actions
@app.action_hook("search")
@mcp_tool(description="Search this actor's properties")
def search(actor: ActorInterface, action_name: str, data: dict):
q = str(data.get("query", "")).lower()
return "\n".join(f"{k}: {v}" for k, v in actor.properties.items()
if q in k.lower() or q in str(v).lower())
# Wire into your web framework of choice
from fastapi import FastAPI
api = FastAPI()
app.integrate_fastapi(api) # or app.integrate_flask(flask_app)
The fluent ``ActingWebApp`` builder auto-generates every protocol route
(``/properties``, ``/trust``, ``/subscriptions``, ``/callbacks``, ``/meta``,
``/actions``, ``/methods``, the OAuth2 endpoints, and ``/mcp``) and wires your
hooks in. You supply configuration and business logic; the framework supplies the
protocol, auth, storage, and client surfaces.
Installation
------------
ActingWeb requires **Python 3.11+**. Install from PyPI with the extras you need:
.. code-block:: bash
# Minimal (no database backend or web framework)
pip install actingweb
# Pick a database backend
pip install 'actingweb[dynamodb]'
pip install 'actingweb[postgresql]'
# Pick a web framework integration
pip install 'actingweb[flask]'
pip install 'actingweb[fastapi]'
# Combine as needed
pip install 'actingweb[fastapi,postgresql]'
# Everything (both backends, both frameworks, MCP)
pip install 'actingweb[all]'
Key capabilities
----------------
Fluent application builder
^^^^^^^^^^^^^^^^^^^^^^^^^^^
``ActingWebApp`` configures the whole application through chained ``with_*``
builders — OAuth providers, Web UI/SPA, MCP, database backend, indexed properties,
subscription processing, peer caching, and more — then integrates with Flask or
FastAPI in one call. Decorator-based hooks (``@app.lifecycle_hook``,
``@app.property_hook``, ``@app.action_hook``, ``@app.method_hook``,
``@app.subscription_hook``, ``@app.callback_hook``) replace the boilerplate
subclassing of older ActingWeb apps.
AI / MCP support
^^^^^^^^^^^^^^^^
``.with_mcp()`` exposes an authenticated MCP server at ``/mcp``. Action and method
hooks annotated with ``@mcp_tool`` / ``@mcp_prompt`` become per-user MCP **tools**
and **prompts**, with safety annotations and input schemas surfaced to the client.
Because each MCP session is bound to an authenticated actor, an LLM only ever sees
and mutates that one user's data. See ``docs/guides/mcp-applications.rst`` and
``docs/guides/mcp-quickstart.rst``.
Authentication: web, SPA, and native mobile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OAuth2 with Google, GitHub, and **Sign in with Apple** is built in, with email
validation, encrypted-state CSRF protection, and login-hint support. Beyond the
server-rendered login, ActingWeb ships a hardened session layer for rich clients:
- **SPA mode** — ``/oauth/spa/*`` endpoints issue short-lived access tokens and
rotating refresh tokens with reuse detection, scoped chain revocation, bounded
retention, and a self-contained expiry purge (no cron/Lambda required).
``with_spa_redirect_origins()`` / ``with_spa_cors_origins()`` support
split-domain deployments.
- **Native mobile** — RFC 8252 authorization-code exchange, RFC 7523 JWT-bearer
grants (``with_google_native()``, ``with_apple_sign_in()``), and single-use
deep-link ``mobile_ticket`` grants (``with_github()`` and Apple-on-Android) so no
IdP code or ActingWeb token ever rides a deep link.
See ``docs/guides/authentication.rst``, ``docs/guides/spa-authentication.rst``, and
``docs/guides/apple-sign-in.rst``.
Trust, permissions, and subscriptions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Per-user trust relationships carry fine-grained permissions that govern what a peer
(or an AI client) may read, write, or call. Subscriptions let one actor be notified
of another's changes, with sync or async callback delivery — use
``.with_sync_callbacks()`` on Lambda/serverless so callbacks complete before the
function freezes. See ``docs/guides/trust-relationships.rst``,
``docs/guides/access-control.rst``, and ``docs/guides/subscriptions.rst``.
Pluggable persistence
^^^^^^^^^^^^^^^^^^^^^^
Two production-ready backends behind a common protocol:
- **DynamoDB** (default) — AWS-managed, auto-scaling, native TTL; ideal for
serverless. Uses PynamoDB / boto3.
- **PostgreSQL** — PostgreSQL 12+ with Alembic migrations and connection pooling.
Install with the ``postgresql`` extra.
Select with ``database="postgresql"`` or the ``DATABASE_BACKEND`` environment
variable. Optional **property reverse-lookup tables** (``with_indexed_properties``)
enable find-actor-by-property-value without GSI size limits. See
``docs/reference/database-backends.rst``.
The ActingWeb model
-------------------
The ActingWeb micro-services model defines bot-to-bot and
service-to-service communication that allows extreme distribution of data and
functionality — well suited to holding small pieces of sensitive data on behalf of
a user or "thing" and sharing them in a granular, revocable way.
The micro-services model
^^^^^^^^^^^^^^^^^^^^^^^^^
The programming model focuses on representing exactly **one small set of
functionality for exactly one user or entity**. The only way to reach that
functionality is through the user's actor and its REST interface — for example
``GET https://mini-app-url/{actor_id}/properties/location``. There is no
cross-actor query, and the security model enforces access per actor: holding a
token for one actor grants nothing on another. Any cross-actor behavior (``xyz``
sharing location with ``yyz``) happens through the standardized ActingWeb REST
protocol, so **any** service that speaks the protocol can interoperate.
The REST protocol
^^^^^^^^^^^^^^^^^
Each actor exposes a set of standard endpoints under its root URL
``https://mini-app-url/{actor_id}``:
- ``/properties`` — attribute/value pairs (flat or nested JSON) to store the
actor's data.
- ``/meta`` — a public structure so actors can discover each other's capabilities.
- ``/trust`` — request, approve, and manage trust relationships with other actors.
- ``/subscriptions`` — establish and manage subscriptions to another actor's paths
once a trust relationship exists.
- ``/callbacks`` — verification during trust/subscription setup, subscription
delivery, and a hook for 3rd-party webhooks.
- ``/resources`` — a skeleton for exposing arbitrary resources where
``/properties`` does not fit.
- ``/actions`` and ``/methods`` — application-defined operations (also surfaced as
MCP tools/prompts).
- ``/oauth`` and ``/oauth/spa/*`` — OAuth2 flows tying an actor to an identity
provider for web, SPA, and native-mobile clients.
The security model
^^^^^^^^^^^^^^^^^^
Trust is between **actors**, not applications. Each instance holding a user's
sensitive data must be connected by a trust relationship to another actor — which
need not be the same type of application. A location-sharing actor could, for
example, establish trust with an emergency-services actor so responders can always
locate the user, while every other relationship remains untouched and independently
revocable.
Trust is established either through an explicit OAuth flow (tying an actor to an
account at Google, GitHub, Apple, etc.) or through a trust-request flow where one
actor requests a relationship that another approves — interactively or
programmatically over REST. The modern OAuth2 layer adds email validation,
encrypted-state CSRF protection, provider auto-detection, and the SPA/native-mobile
session hardening described above.
See `https://actingweb.org/ `_ for the model in depth.
Documentation
-------------
Comprehensive documentation lives in ``docs/`` and is published at
`https://actingweb.readthedocs.io/ `_
(``/en/master`` for the latest ``master`` branch).
============================================ =========================================
Topic Location
============================================ =========================================
Quickstart & getting started ``docs/quickstart/``
Configuration reference ``docs/quickstart/configuration.rst``
Authentication & OAuth2 ``docs/guides/authentication.rst``
SPA authentication ``docs/guides/spa-authentication.rst``
Sign in with Apple ``docs/guides/apple-sign-in.rst``
Building MCP applications ``docs/guides/mcp-applications.rst``
Web UI & routing ``docs/guides/web-ui.rst``, ``docs/reference/routing-overview.rst``
Hooks reference ``docs/reference/hooks-reference.rst``
Trust, access control, subscriptions ``docs/guides/``
Database backends ``docs/reference/database-backends.rst``
SDK & developer API ``docs/sdk/``
============================================ =========================================
Repository and links
---------------------
- **PyPI**: `https://pypi.org/project/actingweb/ `_ (``pip install actingweb``)
- **Source**: `https://github.com/actingweb/actingweb `_
- **Docs**: `https://actingweb.readthedocs.io/ `_
- **Protocol & project home**: `https://actingweb.org/ `_
- **Example application**: `https://github.com/actingweb/actingwebdemo `_ —
a full reference app (MCP + Web/SPA + OAuth2) to develop against.
Contributing
------------
See ``CONTRIBUTING.rst`` for local setup, the development workflow, testing, and
coding standards. In short:
.. code-block:: bash
poetry install --extras all # install with all optional backends/integrations
poetry run pyright actingweb tests # type checking — must be 0 errors
poetry run ruff check actingweb tests # linting — must pass
make test-all-parallel # run the full test suite (900+ tests)
ActingWeb holds a zero-tolerance quality standard: type hints on all functions,
Pyright clean, Ruff clean, and 100% of tests passing before merge.
Releases are decoupled from PRs — PRs merge to ``master`` without version bumps,
and maintainers cut releases by tagging (``vX.Y.Z``), which triggers CI to publish
to PyPI. See ``CLAUDE.md`` and ``CHANGELOG.rst`` for the release process and history.
License
-------
BSD. See ``LICENSE``.