Metadata-Version: 2.4
Name: phoenixflight
Version: 0.3.7
Summary: PhoenixFlight: governance-aware runtime for dynamic agent and workload membership.
Author-email: Kinshuk Dutta <kinshuk.dutta@ieee.org>
License-Expression: MIT
Project-URL: Homepage, https://phoenixflight.app
Project-URL: Repository, https://github.com/KinshukON/DynamicMembershipArchitecture
Project-URL: Documentation, https://phoenixflight.app/docs.html
Project-URL: Bug Tracker, https://github.com/KinshukON/DynamicMembershipArchitecture/issues
Project-URL: Changelog, https://github.com/KinshukON/DynamicMembershipArchitecture/releases
Keywords: phoenixflight,dynamic-membership-architecture,agent-runtime,phoenixfile,flightpacket,pflight,governed-runtime,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS
Requires-Dist: pyyaml>=6.0
Requires-Dist: packaging>=24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: playwright>=1.50; extra == "dev"
Provides-Extra: server
Requires-Dist: SQLAlchemy==1.4.54; extra == "server"
Requires-Dist: prometheus_client==0.25.0; extra == "server"
Requires-Dist: psycopg2-binary==2.9.11; extra == "server"
Provides-Extra: operator
Requires-Dist: kopf==1.38.0; extra == "operator"
Requires-Dist: kubernetes==35.0.0; extra == "operator"
Provides-Extra: all
Requires-Dist: phoenixflight[dev,operator,server]; extra == "all"
Dynamic: license-file

# PhoenixFlight

## Dynamic Membership Runtime for Governed Agent and Workload Handoff

[![CI](https://github.com/KinshukON/DynamicMembershipArchitecture/actions/workflows/ci.yml/badge.svg)](https://github.com/KinshukON/DynamicMembershipArchitecture/actions)
[![Release](https://img.shields.io/badge/Release-v0.3.5--preview-blue)](https://github.com/KinshukON/DynamicMembershipArchitecture/releases/tag/v0.3.5-preview)
[![Python 3.11](https://img.shields.io/badge/Python-3.11-blue)](https://python.org)
[![Tests](https://img.shields.io/badge/Tests-203%20passing-success)](#)
[![License](https://img.shields.io/github/license/KinshukON/DynamicMembershipArchitecture)](LICENSE)
[![Website](https://img.shields.io/badge/site-phoenixflight.app-blue)](https://phoenixflight.app)
[![Research DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20693483.svg)](https://doi.org/10.5281/zenodo.20693483)
[![Software DOI](https://img.shields.io/badge/DOI/10.5281/zenodo.20778458.svg)](https://doi.org/10.5281/zenodo.20778458)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0002--6039--549X-green)](https://orcid.org/0009-0002-6039-549X)


PhoenixFlight is a local dynamic membership runtime for registering, discovering, assigning, handing off, retiring, and auditing agents, services, tools, and workload packets. It is based on Dynamic Membership Architecture, a framework for systems where computational participants dynamically join, leave, migrate, fail, recover, and retire while preserving execution continuity.

PhoenixFlight complements Docker and Kubernetes by adding a governance-aware membership contract for agentic and distributed runtime participation. It is a local MVP runtime backed by research-grade architecture.

### The Hub Model
Use the `hub` commands to view and pull governed templates, enabling reusable configurations across teams without rewriting `PhoenixFile` specs from scratch.

### Scenario Packs
PhoenixFlight provides powerful **scenario packs** to quickly scaffold governed runtimes for different use cases:
- `governed-agent-runtime`: Demonstrates governed multi-agent task execution with planner, worker, reviewer, and governance members.
- `enterprise-approval-flow`: Demonstrates approval-gated workload progression with policy checks and audit events.

See [Scenario Packs](docs/SCENARIO_PACKS.md) for more details.

## Development and Testing

> [!IMPORTANT]
> **Technical Specification:** Read the [Technical Blueprint](https://github.com/KinshukON/DynamicMembershipArchitecture/blob/main/docs/technical_blueprint.md) for an in-depth structural and mathematical specification of the Dynamic Membership Architecture (DMA) implementation.

---

## v0.3 Preview Capabilities

PhoenixFlight v0.3 Preview includes the following capabilities:
- **PhoenixFile** declarative manifest model
- **Flight Packets** for portable workload routing
- **Member Registration**, **Discovery**, **Assignment**, **Handoff**, **Retirement**, and **Audit** tracking
- **Local PhoenixHub Catalog** for scaffolding built-in templates
- **Remote PhoenixHub MVP** for safe package discovery and caching
- **Hybrid Quantum-Classical Scenario Pack**

### Remote Hub Safety Model
> "Remote Hub pull means cache and verify. It does not mean run. Pulled packages are inert files and are never executed, imported, registered, activated, or run automatically."

### Quantum Positioning
> "PhoenixFlight does not execute quantum circuits directly and does not replace quantum providers. The hybrid quantum-classical scenario pack is a mock/reference architecture demonstrating DMA-based orchestration around simulators, provider adapters, optimization agents, and result auditors."

---

## Product Mental Model

```
PhoenixFile  →  .pflight bundle  →  governed runtime execution  →  assignment  →  handoff  →  audit
```

| Stage | What happens |
|---|---|
| **PhoenixFile** | Declare participants, policies, capabilities, and governance contracts |
| **.pflight bundle** | Package + cryptographically verify the application for portable deployment |
| **Governed runtime** | Initialize the local runtime; register agents as members |
| **Assignment** | Policy-route a FlightPacket to the best-match member by trust + capability |
| **Handoff** | Migrate context from one member to another, preserving full lineage |
| **Audit** | Every event — register, assign, handoff, retire — written to JSONL audit trail |

---

## 60-Second Quickstart

Get started with PhoenixFlight immediately via PyPI:

```bash
# 1. Install PhoenixFlight
pip install phoenixflight
# Or macOS/Linux via Homebrew: brew tap KinshukON/tap && brew install phoenixflight
# Or run via Docker: docker run --rm ghcr.io/kinshukon/phoenixflight:v0.3.5-preview phoenix

# 2. Scaffold a new governed application
phoenix new my-app
cd my-app

# 3. Initialize local runtime
phoenix init

# 4. Validate the declarative app descriptor
phoenix validate -f PhoenixFile

# 5. Register the agent
phoenix member register agents/my-app-agent.yaml

# 6. Create a workload packet
phoenix packet create my-app

# 7. Auto-assign the packet based on capability and trust policy
phoenix assign packet-001 --to my-app-agent

# 8. Check your runtime status
phoenix status

# 9. Build a portable, signed .pflight bundle
phoenix build -f PhoenixFile
```


# Scaffold a new app
phoenix new my-app

# Inspect local runtime state at any time
phoenix status
```

`phoenix status` is the fastest way to inspect your local runtime: it prints a one-screen summary of initialization state, member counts, packet counts, and the most recent audit event. It exits 0 whether or not the runtime has been initialized, so it is safe to run at any point in the workflow. Use `phoenix --no-color status` in CI or when piping output to a file.

### Shell Completion

PhoenixFlight can generate completion scripts for bash, zsh, and fish:

```bash
phoenix completion bash > ~/.phoenix-completion.bash && source ~/.phoenix-completion.bash  # bash
phoenix completion zsh  > ~/.zsh/completions/_phoenix                                      # zsh
phoenix completion fish > ~/.config/fish/completions/phoenix.fish                          # fish
```

Both `phoenix` and `pf` are covered by each generated script. Full install instructions are in [docs/INSTALL.md](docs/INSTALL.md).

See [docs/INSTALL.md](docs/INSTALL.md) for pipx, pip, Homebrew, and container install paths. See [docs/CHANGELOG.md](docs/CHANGELOG.md) for version history and [docs/RELEASE.md](docs/RELEASE.md) for the release runbook.

---


Watch PhoenixFlight register governed members, assign a FlightPacket, perform a handoff, write an audit trail, and build a verified `.pflight` bundle.

![PhoenixFlight v0.1.0 MVP terminal demo](media/phoenixflight-v0.1.0-demo.gif)

> Full walkthrough video available in the [v0.1.0-mvp release assets](https://github.com/KinshukON/DynamicMembershipArchitecture/releases/tag/v0.1.0-mvp).

---

## What PhoenixFlight Is

PhoenixFlight is a **local governance-aware runtime** that implements Dynamic Membership Architecture for real workloads and agents. It provides:

- A declarative application descriptor — **PhoenixFile** — describing participants, governance policies, and runtime contracts
- A portable unit of work — **FlightPacket** — that carries identity, capabilities, context, and audit history
- A packaged distribution format — **`.pflight` bundle** — for portable, cryptographically-verified deployment
- A **CLI and REST API** for the full membership lifecycle
- A **policy engine** for trust-scored, capability-routed assignment and handoff
- An **audit trail** capturing every membership event in structured JSONL

---

## Why It Exists

Modern distributed and agentic systems assume static participants. When an agent crashes, a service migrates, or a workload is handed off between providers, most frameworks lose context, history, and governance continuity.

Dynamic Membership Architecture formalizes the contract for systems where **membership is the variable**, not the exception. PhoenixFlight is the reference implementation of that contract.

PhoenixFlight does **not** claim to replace Docker or Kubernetes. Correct framing:

> PhoenixFlight adds governance-aware membership semantics — registration, trust, assignment, handoff, retirement, and audit — to complement the infrastructure scheduling and container packaging layers provided by Docker and Kubernetes.

---

## Emerging Use Case: Hybrid Quantum-Classical Workloads

PhoenixFlight can be positioned as a Dynamic Membership Runtime that orchestrates the classical control plane around hybrid quantum-classical workloads. 

**Disclaimer:** PhoenixFlight does not execute quantum circuits directly and does not replace quantum providers (like IBM Quantum, AWS Braket, Azure Quantum, etc.).

Quantum workloads rely on dynamically available QPUs, fallback simulators, dynamic pricing, queue states, and classical optimization agents. PhoenixFlight models these participants as dynamic members, assigning Flight Packets (jobs) based on policies, handling fallback via handoff, and ensuring rigorous audit lineage for experiments.

---

## Core Runtime Lifecycle

```
Register → Discover → Assign → Handoff → Retire → Audit
```

| Step | What happens |
|---|---|
| **Register** | An agent or service joins the runtime with identity, capabilities, trust score, and namespace |
| **Discover** | The runtime finds eligible members matching required capabilities and trust thresholds |
| **Assign** | A FlightPacket is assigned to a member using policy-governed, trust-weighted capability routing |
| **Handoff** | A packet migrates from one member to another, preserving context, history, and ownership |
| **Retire** | A member gracefully drains its assignments and exits the runtime with an audit trail |
| **Audit** | Every event — registration, assignment, handoff, retirement, denial — is written to the audit log |

---

## PhoenixFile

`PhoenixFile` is the canonical declarative application descriptor for a governed participant group. It replaces nothing — it is the native PhoenixFlight contract.

```yaml
apiVersion: phoenixflight.io/v1alpha1
kind: PhoenixApp
metadata:
  name: customer-validation-app
  namespace: tenant-a
  version: 0.1.0

runtime:
  language: python
  entrypoint: src/app.py

controlPlane:
  auth:
    provider: local
  policies:
    - policies/can-register.yaml
    - policies/can-assign.yaml
    - policies/can-handoff.yaml
  audit:
    sink: local
    format: jsonl
  assignment:
    strategy: trust-weighted-capability-routing
  governance:
    minimumTrustScore: 0.85

dataPlane:
  agents:
    - agents/governance-agent.yaml
    - agents/metadata-agent.yaml
  packets:
    - packets/customer-validation.packet.yaml
  handoffContracts:
    - contracts/customer-context-handoff.yaml

membership:
  discovery:
    mode: capability
  migration:
    enabled: true
  retirement:
    drainTimeoutSeconds: 30
```

Full spec: [docs/PHOENIXFILE.md](docs/PHOENIXFILE.md)

---

## FlightPacket

A FlightPacket is a portable unit of work. It carries:

- **Workload identity and namespace**
- **Required capability constraints**
- **Context payload** (checkpoint state)
- **Policy tags** (e.g., PII, GDPR)
- **Ownership history** (full handoff chain)
- **Audit lineage**

Packets are created from YAML manifests, assigned to members via trust-weighted routing, handed off between members preserving context, and audited at every transition.

---

## `.pflight` Bundle

A `.pflight` bundle is a portable, signed runtime archive:

```
customer-validation-app-0.1.0.pflight (ZIP)
├── PhoenixFile
├── manifest.json
├── validation-report.json
├── hashes.json              ← SHA-256 for all files
├── agents/
├── packets/
├── policies/
└── contracts/
```

Build, inspect, verify, and unpack:

```bash
python3 -m src.phoenix_cli build -f examples/customer-validation/PhoenixFile
python3 -m src.phoenix_cli bundle inspect dist/customer-validation-app-0.1.0.pflight
python3 -m src.phoenix_cli bundle verify  dist/customer-validation-app-0.1.0.pflight
python3 -m src.phoenix_cli bundle unpack  dist/customer-validation-app-0.1.0.pflight --to ./unpacked
```

Full spec: [docs/BUNDLE_FORMAT.md](docs/BUNDLE_FORMAT.md)

---

## Local Runtime State

## Preview Container Verification

Container images for preview releases are built and pushed to GitHub Container Registry (GHCR) for verification purposes.

> **Warning:** Do not use the `latest` tag for preview releases. The `latest` tag is intentionally disabled during the preview phase. You must use the exact semantic version tag.

```bash
# Pull the exact preview image
```

PhoenixFlight stores all runtime state under `.phoenixflight/`:

```
.phoenixflight/
├── members.json      ← registered member registry
├── packets.json      ← active flight packets
├── audit.jsonl       ← structured audit log
└── imports/          ← local bundle registry
```

Initialize:

```bash
python3 -m src.phoenix_cli init
```

---

## CLI Quickstart

### Prerequisites

```bash
git clone https://github.com/KinshukON/DynamicMembershipArchitecture.git
cd DynamicMembershipArchitecture
pip install -e .
```

### Full Local Demo

```bash
# 1. Initialize local runtime state
phoenix init

# 2. Validate a PhoenixFile
phoenix validate -f examples/customer-validation/PhoenixFile

# 3. Register members (agents)
phoenix member register examples/customer-validation/agents/governance-agent.yaml
phoenix member register examples/customer-validation/agents/metadata-agent.yaml

# 4. List members
phoenix member list

# 5. Create a flight packet
phoenix packet create customer-validation

# 6. List packets
phoenix packet list

# 7. Assign packet to a member (auto policy-checked)
phoenix assign packet-001 --to governance-agent

# 8. Inspect a packet
phoenix inspect packet-001

# 9. Handoff to another member
phoenix handoff packet-001 --from governance-agent --to metadata-agent

# 10. Retire a member
phoenix retire governance-agent

# 11. View audit log
phoenix audit

# 12. Build a portable .pflight bundle
phoenix build -f examples/customer-validation/PhoenixFile

# 13. Inspect the bundle
phoenix bundle inspect dist/customer-validation-app-0.1.0.pflight

# 14. Cryptographically verify bundle integrity
phoenix bundle verify dist/customer-validation-app-0.1.0.pflight

# 15. Unpack a bundle
phoenix bundle unpack dist/customer-validation-app-0.1.0.pflight --to ./unpacked

# 16. Emit a Dockerfile from PhoenixFile
phoenix emit dockerfile -f examples/customer-validation/PhoenixFile

# 17. Worker lifecycle
phoenix worker start     --id worker-01
phoenix worker heartbeat --id worker-01
phoenix worker retire    --id worker-01

# 18. Local registry
phoenix registry add     dist/customer-validation-app-0.1.0.pflight
phoenix registry list
phoenix registry inspect customer-validation-app
```

### Developer fallback (no install required)

If you do not run `pip install -e .`, use the direct module invocation:

```bash
PYTHONPATH=. python3 -m src.phoenix_cli init
PYTHONPATH=. python3 -m src.phoenix_cli version
```

Full reference: [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)

---

## PhoenixHub (Local Catalog)

PhoenixFlight ships with a built-in local catalog of certified templates. This allows you to rapidly scaffold governance-ready agent architectures.

```bash
# List all available built-in templates
phoenix hub list

# View details for a specific template
phoenix hub show customer-validation

# Scaffold a new app using the customer-validation template
phoenix new my-app --template customer-validation
```

> **Note on Phase 3A:** The current PhoenixHub implementation is completely local. The catalog and templates are bundled into the Python package (`src/hub`). There is no remote registry connection, meaning it is air-gap friendly.
> 
> **Note on Security:** The workspace dashboard provided in `PhoenixFlight.app` uses a client-side auth guard for early-access placeholder routing. It is not intended for protecting sensitive backend data in production environments.

---

## API Quickstart

Start the API server:

```bash
python3 src/server.py --port 8000
```

PhoenixFlight includes an early Runtime Console preview. The roadmap matures this into Mission Control: a work-centric control plane for observing Flight Packets, runtime members, handoffs, governance events, and audit lineage.

Open `http://localhost:8000` in your browser for the runtime console and dashboard.

REST API reference: [docs/API.md](docs/API.md)

---

## Enterprise Readiness

| Capability | Status |
|---|---|
| PhoenixFile declarative descriptor | ✅ Implemented |
| Dynamic member registry | ✅ Implemented |
| Trust-weighted capability assignment | ✅ Implemented |
| Policy-governed handoff | ✅ Implemented |
| Graceful member retirement | ✅ Implemented |
| Portable `.pflight` bundle (SHA-256 verified) | ✅ Implemented |
| Bundle verification (strict integrity check) | ✅ Implemented |
| Dockerfile emitter from PhoenixFile | ✅ Implemented |
| Structured audit trail (JSONL) | ✅ Implemented |
| SIEM audit export | ✅ Implemented |
| Runtime worker lifecycle | ✅ Implemented |
| Auth dev mode / JWT enforcement mode | ✅ Implemented |
| Namespace isolation | ✅ Implemented |
| Local bundle registry | ✅ Implemented |
| Production JWT + OIDC | 🔲 Roadmap |
| Multi-node distributed registry | 🔲 Roadmap |
| Kubernetes operator | 🔲 Roadmap |

Full assessment: [docs/ENTERPRISE_READINESS.md](docs/ENTERPRISE_READINESS.md)

---

## Research Foundation

PhoenixFlight implements **Dynamic Membership Architecture (DMA)** — a formal framework for systems where participants dynamically join, leave, migrate, fail, recover, and retire while preserving execution continuity.

The DMA framework covers three major paradigms:

1. **Phoenix-style virtual nodes** — consistent hashing across a dynamic membership ring
2. **Kubernetes-style constraint scheduling** — capacity-scored workload placement
3. **Agentic AI registries** — capability-based routing with reliability scoring

The research demonstrates that all three paradigms instantiate the same six primitives: Identity, Discovery, Assignment, Migration, Retirement, Governance.

### Running the Research Simulator

```bash
python3 src/main.py
python3 src/main.py --steps 120 --initial-resources 8 --imbalance-threshold 0.10 --seed 101
```

### Research Materials

- `paper/` — Technical paper (PDF and DOCX)
- `figures/` — Architecture diagrams
- `docs/technical_blueprint.md` — Formal mathematical specification
- `docs/ARCHITECTURE.md` — Internal design specification

---

## Current Limitations

- **Local-only runtime:** PhoenixFlight currently runs on a single machine. Distributed multi-node registry is on the roadmap.
- **No production auth by default:** `PHOENIX_AUTH_MODE=dev` is the default. Set `PHOENIX_AUTH_MODE=jwt` with `PHOENIX_JWT_SECRET` for JWT enforcement.
- **Worker executes mock tasks only:** The runtime worker uses safe non-shell handlers. Real task execution is not implemented.
- **No container image registry:** The Dockerfile emitter generates a file for review; image push requires Docker to be installed and run separately.
- **SQLite state:** Runtime state is stored in SQLite (`phoenixflight.db`) for local persistence. No distributed store.

---

## Roadmap

- Production JWT/OIDC auth integration
- Multi-node distributed registry with leader election
- Kubernetes operator (`Dockerfile.operator`)
- LangGraph and LangChain adapter (in progress — `src/langgraph_adapter.py`)
- Live migration with checkpoint transfer
- Verifiable audit log (hash chain / Merkle)
- Helm chart for Kubernetes deployment

See [docs/ROADMAP.md](docs/ROADMAP.md) for details.

---

## DOI Records

PhoenixFlight is connected to two related but distinct archival records:

| Artifact | Type | DOI |
|---|---|---|
| Dynamic Membership Architecture paper | Publication / manuscript | https://doi.org/10.5281/zenodo.20693483 |
| PhoenixFlight runtime | Software artifact / GitHub release archive | https://doi.org/10.5281/zenodo.20778458 |

The publication DOI refers to the Dynamic Membership Architecture research manuscript.  
The software DOI refers to the runnable PhoenixFlight implementation and GitHub release archive.

---

## Citation / DOI / ORCID / Author

Please cite the v1.0.0 Zenodo publication as:

Dutta, K. (2026). *Dynamic Membership Architecture: From the Phoenix Computing Model to Cloud-Native and Agentic AI Runtime Systems* (v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.20693483

```bibtex
@misc{dutta2026dynamicmembershiparchitecture,
  author       = {Dutta, Kinshuk},
  title        = {Dynamic Membership Architecture: From the Phoenix Computing Model to Cloud-Native and Agentic AI Runtime Systems},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.20693483},
  url          = {https://doi.org/10.5281/zenodo.20693483}
}
```

### DOIs

- Version DOI (v1.0.0): https://doi.org/10.5281/zenodo.20693483
- Concept DOI (all versions): https://doi.org/10.5281/zenodo.20693482

### Links

- Zenodo v1.0.0: https://doi.org/10.5281/zenodo.20693483
- Zenodo all-versions: https://doi.org/10.5281/zenodo.20693482
- GitHub release v1.0.0: https://github.com/KinshukON/DynamicMembershipArchitecture/releases/tag/v1.0.0
- Author ORCID: https://orcid.org/0009-0002-6039-549X
- Author website: https://kinshukdutta.ai
- Live site: https://phoenixflight.app

---

## Provenance

PhoenixFlight and the Dynamic Membership Architecture implementation are originated and authored by Kinshuk Dutta.

Passive provenance marker: `PF-DMA-KD-ORIGIN-2026-PHOENIXFLIGHT`
