portworld 0.2.0__tar.gz

portworld-0.2.0/LICENSE

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

portworld-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+global-exclude *.py[cod]
+global-exclude .DS_Store
+prune */__pycache__
+prune backend

portworld-0.2.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: portworld
+Version: 0.2.0
+Summary: PortWorld CLI for setup, self-hosting, and managed deploy workflows
+Author: PortWorld Maintainers
+Maintainer: PortWorld Maintainers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/portworld/PortWorld
+Project-URL: Repository, https://github.com/portworld/PortWorld
+Project-URL: Issues, https://github.com/portworld/PortWorld/issues
+Project-URL: Documentation, https://github.com/portworld/PortWorld/blob/main/portworld_cli/README.md
+Keywords: ai,backend,cli,cloud-run,meta,rayban-meta,glasses,portworld,realtime,self-hosting
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: annotated-types==0.7.0
+Requires-Dist: anyio==4.11.0
+Requires-Dist: certifi==2025.11.12
+Requires-Dist: click==8.3.1
+Requires-Dist: boto3==1.40.74
+Requires-Dist: botocore==1.40.74
+Requires-Dist: fastapi==0.109.2
+Requires-Dist: h11==0.16.0
+Requires-Dist: httpcore==1.0.9
+Requires-Dist: httptools==0.7.1
+Requires-Dist: httpx==0.28.1
+Requires-Dist: idna==3.11
+Requires-Dist: InquirerPy==0.3.4
+Requires-Dist: mcp==1.12.4
+Requires-Dist: azure-identity==1.25.1
+Requires-Dist: azure-storage-blob==12.27.1
+Requires-Dist: google-cloud-storage==2.19.0
+Requires-Dist: Pillow==12.0.0
+Requires-Dist: psycopg[binary]==3.2.10
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pydantic-core==2.41.5
+Requires-Dist: python-dotenv==1.0.1
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: rich==13.9.4
+Requires-Dist: sniffio==1.3.1
+Requires-Dist: starlette==0.36.3
+Requires-Dist: typing-extensions==4.15.0
+Requires-Dist: typing-inspection==0.4.2
+Requires-Dist: uvicorn[standard]==0.27.1
+Requires-Dist: websockets==15.0.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Dynamic: license-file
+
+# PortWorld CLI
+
+Command-line interface for bootstrapping, validating, and deploying [PortWorld](https://github.com/portworld/PortWorld) — the open-source runtime for voice-and-vision AI assistants.
+
+## Install
+
+**Recommended** (with [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv tool install portworld
+```
+
+With pipx:
+
+```bash
+pipx install portworld
+```
+
+Bootstrap installer (installs `uv`, Python 3.11+, and Node.js tooling if missing):
+
+```bash
+curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/portworld/PortWorld/main/install.sh | bash
+```
+
+## Agent skill (Cursor, Codex, others)
+
+Install the **portworld-cli-autopilot** skill so agents get consistent bootstrap and operator commands ([Agent Skills](https://agentskills.io) format):
+
+```bash
+npx skills add portworld/PortWorld --skill portworld-cli-autopilot -a cursor -a codex -y
+```
+
+Direct install of the skill folder only:
+
+```bash
+npx skills add https://github.com/portworld/PortWorld/tree/main/skills/portworld-cli-autopilot -y
+```
+
+See [skills/README.md](https://github.com/portworld/PortWorld/blob/main/skills/README.md) for `--list`, `-g` (global), and telemetry options.
+
+## Requirements
+
+- macOS or Linux
+- Python 3.11+
+- Docker for local published-workspace runs
+
+## Quickstart
+
+Initialize a local workspace, configure providers, and start the backend:
+
+```bash
+portworld init
+```
+
+Validate and inspect:
+
+```bash
+portworld doctor --target local
+portworld status
+```
+
+`portworld init` supports two setup modes:
+
+- `quickstart` — guided onboarding with beginner-friendly defaults
+- `manual` — guided onboarding with advanced choices like local source runtime
+
+Force either mode with `--setup-mode quickstart` or `--setup-mode manual`.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `portworld init` | Run the onboarding wizard, write config, and execute the selected local or managed path |
+| `portworld doctor` | Validate local or managed deployment readiness |
+| `portworld deploy` | Deploy to a managed cloud target |
+| `portworld status` | Inspect workspace and deploy state |
+| `portworld logs` | Read managed deployment logs |
+| `portworld config` | Inspect or edit project configuration |
+| `portworld providers` | Browse supported realtime, vision, search, and cloud providers |
+| `portworld extensions` | Manage extension manifests and install state |
+| `portworld update cli` | Show the recommended CLI upgrade command |
+| `portworld update deploy` | Redeploy the active managed target |
+| `portworld ops` | Lower-level operator tasks (see below) |
+
+### Operator Tasks
+
+```bash
+portworld ops check-config                   # validate local config
+portworld ops check-config --full-readiness  # full preflight with provider validation
+portworld ops bootstrap-storage              # initialize storage
+portworld ops export-memory --output /tmp/portworld-memory-export.zip
+```
+
+## Deploy Workflows
+
+Supported managed targets: **GCP Cloud Run**, **AWS ECS/Fargate**, **Azure Container Apps**.
+
+### Readiness Check
+
+```bash
+portworld doctor --target gcp-cloud-run    --gcp-project <project> --gcp-region <region>
+portworld doctor --target aws-ecs-fargate  --aws-region <region>
+portworld doctor --target azure-container-apps --azure-subscription <sub> --azure-resource-group <rg> --azure-region <region>
+```
+
+### Deploy
+
+```bash
+portworld deploy gcp-cloud-run   --project <project> --region <region>
+portworld deploy aws-ecs-fargate --region <region>
+portworld deploy azure-container-apps --subscription <sub> --resource-group <rg> --region <region>
+```
+
+### Logs
+
+```bash
+portworld logs gcp-cloud-run       --since 24h --limit 50
+portworld logs aws-ecs-fargate     --since 24h --limit 50
+portworld logs azure-container-apps --since 24h --limit 50
+```
+
+### Redeploy
+
+```bash
+portworld update deploy
+portworld update deploy --tag <image-tag>
+```
+
+## Source Checkout
+
+Use a repo checkout when developing PortWorld itself:
+
+```bash
+git clone https://github.com/portworld/PortWorld.git
+cd PortWorld
+pipx install . --force
+portworld init
+```
+
+## Updating
+
+Upgrade the CLI:
+
+```bash
+uv tool upgrade portworld
+```
+
+Install a pinned version:
+
+```bash
+uv tool install "portworld==<version>"
+```
+
+Upgrade via the bootstrap installer:
+
+```bash
+curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/portworld/PortWorld/main/install.sh | bash -s -- --version v<version>
+```
+
+## Production Caution
+
+Managed cloud workflows are supported, but some infrastructure defaults favor quick bring-up over locked-down security:
+
+- **AWS**: one-click deploy provisions RDS with public accessibility and broad ingress
+- **Azure**: one-click deploy provisions PostgreSQL with public access
+
+Review and harden these defaults before exposing a deployment to the public internet.
+
+## Links
+
+- [Repository](https://github.com/portworld/PortWorld)
+- [Backend README](https://github.com/portworld/PortWorld/blob/main/backend/README.md) — runtime, API reference, configuration
+- [iOS README](https://github.com/portworld/PortWorld/blob/main/IOS/README.md) — iOS app setup, Meta DAT, permissions
+- [Getting Started](https://github.com/portworld/PortWorld/blob/main/GETTING_STARTED.md) — extended onboarding guide
+- [Changelog](https://github.com/portworld/PortWorld/blob/main/CHANGELOG.md)
+- [CLI Release Process](https://github.com/portworld/PortWorld/blob/main/docs/operations/CLI_RELEASE_PROCESS.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/portworld/PortWorld/blob/main/LICENSE).

portworld-0.2.0/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="Port World logo.png" width="100%" alt="Port:World Logo">
+</p>
+
+<p align="center">
+  <strong>Open-source runtime for voice-and-vision AI assistants connected to the real world.</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="#quickstart"><img src="https://img.shields.io/badge/CLI-installer-3775A9" alt="PortWorld CLI installer" /></a>
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
+  <img src="https://img.shields.io/badge/iOS-17%2B-black" alt="iOS 17+" />
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey" alt="Platform" />
+</p>
+
+---
+
+## What if AI could see the world the way we do?
+
+**Port:World** is an open source framework that lets anyone connect their Meta glasses to any AI.
+The AI sees exactly what the wearer sees and can respond with voice, reasoning, or actions.
+
+The use cases are infinite: connect your AI agents, customize them, prompt them, link your MCP, connect your OpenClaw…
+
+It connects an iOS app running on Meta glasses to a FastAPI backend that handles video streaming, AI inference, voice responses, and tool execution. You define the prompts and domain logic. Port:World handles the streaming, model routing, and real-time communication.
+
+Built during the Mistral Worldwide Hackathon 2026 by **Pierre Haas, Vassili de Rosen, Arman Artola.**
+
+<p align="center">
+  🏆 <strong>We finished top 10 out of 600 teams worldwide + won the Giant Venture prize "futur unicorn prize".</strong> 🏆
+</p>
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+  iOS["iOS App"] -->|"WebSocket audio"| Backend["FastAPI Backend"]
+  iOS -->|"Vision frames"| Backend
+  CLI["portworld CLI"] -->|"init / deploy / doctor"| Backend
+  Backend -->|"Realtime relay"| Providers["AI Providers"]
+  Backend -->|"Persistent memory"| Storage["Local / Cloud Storage"]
+```
+
+| Surface | Description |
+|---------|-------------|
+| **[backend/](backend/)** | FastAPI server — realtime voice relay, memory, vision processing, tooling |
+| **[portworld_cli/](portworld_cli/)** | CLI — bootstrap, validate, deploy, and operate PortWorld |
+| **[portworld_shared/](portworld_shared/)** | Shared Python contracts between CLI and backend |
+| **[IOS/](IOS/)** | SwiftUI iOS app — connects Meta smart glasses to your backend |
+
+## Features
+
+- **Realtime voice relay** — bridges WebSocket audio sessions to OpenAI Realtime or Gemini Live
+- **Persistent memory** — per-session and cross-session markdown memory with configurable retention
+- **Visual memory** — ingests camera frames from Meta glasses, runs adaptive scene-change gating, and builds semantic memory via pluggable vision providers
+- **Durable-memory consolidation** — rewrites long-term user memory at session close
+- **Realtime tooling** — memory recall and web search tools injected into the active AI session
+- **Multi-provider support** — 8 vision providers, 2 realtime providers, web search via Tavily
+- **Cloud deployment** — one-command deploy to GCP Cloud Run, AWS ECS/Fargate, or Azure Container Apps
+- **Meta smart glasses** — full DAT integration for audio I/O and vision capture through Ray-Ban Meta glasses
+- **Bearer token auth and rate limiting** — production-ready security defaults
+
+## Quickstart
+
+### Run PortWorld (without cloning)
+
+Install the CLI and bootstrap a local workspace:
+
+```bash
+curl -fsSL --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/portworld/PortWorld/main/install.sh | bash
+portworld init
+```
+
+Verify:
+
+```bash
+portworld doctor --target local
+portworld status
+```
+
+### Backend contributor
+
+Clone the repo and start the backend with Docker:
+
+```bash
+git clone https://github.com/portworld/PortWorld.git
+cd PortWorld
+cp backend/.env.example backend/.env
+# Edit backend/.env — set OPENAI_API_KEY or GEMINI_LIVE_API_KEY
+docker compose up --build
+```
+
+Verify:
+
+```bash
+curl http://127.0.0.1:8080/livez
+# → {"status":"ok","service":"portworld-backend"}
+```
+
+### iOS contributor
+
+Start the backend (see above), then open the iOS project:
+
+```bash
+open IOS/PortWorld.xcodeproj
+```
+
+1. Let Xcode resolve Swift Package dependencies.
+2. Build the **PortWorld** scheme.
+3. Configure the backend URL in the app and validate the connection.
+
+## Minimum Viable Environment
+
+You only need **one API key** to get started. Pick a realtime provider:
+
+| Provider | Set in `backend/.env` |
+|----------|----------------------|
+| OpenAI Realtime | `REALTIME_PROVIDER=openai` and `OPENAI_API_KEY=sk-...` |
+| Gemini Live | `REALTIME_PROVIDER=gemini_live` and `GEMINI_LIVE_API_KEY=...` |
+
+Everything else (vision, tooling, consolidation) is off by default and can be enabled incrementally. See [backend/README.md](backend/README.md) for the full configuration reference.
+
+## Supported Providers
+
+### Realtime
+
+| Provider | ID | Required Key |
+|----------|----|--------------|
+| OpenAI Realtime | `openai` | `OPENAI_API_KEY` |
+| Gemini Live | `gemini_live` | `GEMINI_LIVE_API_KEY` |
+
+### Vision (opt-in)
+
+| Provider | ID | Required Key(s) |
+|----------|----|-----------------|
+| Mistral | `mistral` | `VISION_MISTRAL_API_KEY` |
+| NVIDIA Integrate | `nvidia_integrate` | `VISION_NVIDIA_API_KEY` |
+| OpenAI | `openai` | `VISION_OPENAI_API_KEY` |
+| Azure OpenAI | `azure_openai` | `VISION_AZURE_OPENAI_API_KEY` + `VISION_AZURE_OPENAI_ENDPOINT` |
+| Gemini | `gemini` | `VISION_GEMINI_API_KEY` |
+| Claude | `claude` | `VISION_CLAUDE_API_KEY` |
+| AWS Bedrock | `bedrock` | `VISION_BEDROCK_REGION` (+ optional IAM credentials) |
+| Groq | `groq` | `VISION_GROQ_API_KEY` |
+
+### Search (opt-in)
+
+| Provider | ID | Required Key |
+|----------|----|--------------|
+| Tavily | `tavily` | `TAVILY_API_KEY` |
+
+Use `portworld providers list` and `portworld providers show <id>` to inspect providers from the CLI.
+
+## Cloud Deployment
+
+Deploy to managed cloud targets with the CLI:
+
+```bash
+portworld deploy gcp-cloud-run   --project <project> --region <region>
+portworld deploy aws-ecs-fargate --region <region>
+portworld deploy azure-container-apps --subscription <sub> --resource-group <rg> --region <region>
+```
+
+See the [CLI README](portworld_cli/README.md) for readiness checks, log streaming, and redeployment.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [backend/README.md](backend/README.md) | Backend runtime, API reference, configuration, storage |
+| [portworld_cli/README.md](portworld_cli/README.md) | CLI installation, commands, deploy workflows |
+| [IOS/README.md](IOS/README.md) | iOS app setup, Meta DAT, permissions, architecture |
+| [GETTING_STARTED.md](GETTING_STARTED.md) | Extended onboarding guide with all setup paths |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
+| [docs/operations/CLI_RELEASE_PROCESS.md](docs/operations/CLI_RELEASE_PROCESS.md) | CLI release and versioning process |
+
+## Status
+
+PortWorld is in its first stable release cutover. The core product surfaces are release-ready, while managed deploy hardening and operator-facing documentation continue to improve.
+
+**Stable-targeted:** backend self-hosting, CLI bootstrap and deploy workflows, and the iOS app with Meta glasses integration.
+
+**Release rollout:** the first public PyPI publication and GitHub release packaging land with the `v0.2.0` release cut.
+
+**Hardening:** managed cloud deploy defaults, public-facing operator documentation, production security posture for one-click deploys.
+
+### Known Limitations
+
+- Provider API keys are required for runtime use — there is no keyless demo mode.
+- AWS and Azure one-click deploys provision databases with public access by default. Review and tighten before production use.
+- Full iOS runtime validation requires a reachable backend and, for glasses features, supported Meta hardware with the Meta AI app.
+- The shared Xcode schemes do not currently include a maintained test action.
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+- Bug reports and feature requests: [open an issue](https://github.com/portworld/PortWorld/issues)
+- Security vulnerabilities: see [SECURITY.md](SECURITY.md)
+- Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+
+Do not post secrets, tokens, private URLs, or unredacted production logs in public issues.
+
+## License
+
+MIT — see [LICENSE](LICENSE).