Metadata-Version: 2.4
Name: palonexus
Version: 0.1.0
Summary: PaloNexus SDK — one typed, framework-aware front door over the agent control plane (facade + 10 models + typed errors + DID/VC crypto + idp client). One install: the agentdid + idp_sdk foundations are bundled in. Framework weight is opt-in via extras.
Project-URL: Homepage, https://github.com/rogerchucker/palonexus-platform
Project-URL: Repository, https://github.com/rogerchucker/palonexus-platform
Author: PaloNexus
License: Proprietary
Keywords: agent,audit,authorization,delegation,egress,iam,langchain,langgraph
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyjwt[crypto]>=2.8
Provides-Extra: all
Requires-Dist: deepagents>=0.0.1; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: langchain>=0.3; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Requires-Dist: opentelemetry-api>=1.24; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Provides-Extra: deepagents
Requires-Dist: deepagents>=0.0.1; extra == 'deepagents'
Provides-Extra: langchain
Requires-Dist: langchain>=0.3; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: uvicorn>=0.29; extra == 'server'
Provides-Extra: test
Requires-Dist: mypy>=1.8; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# palonexus

The consolidated, typed, framework-aware **PaloNexus SDK** — one installable
front door over the agent control plane. It *wraps* (does not replace) the three
existing packages, per Appendix B.1 of the SDK & Documentation Update Plan: a
**lean core** plus **optional framework extras** in a uv/pip workspace.

```
pip install palonexus                # core: facade, 10 models, typed errors, idp client, crypto
pip install 'palonexus[langchain]'   # + middleware(), guarded_tool()
pip install 'palonexus[langgraph]'   # + governed_node, resume_after_approval
pip install 'palonexus[deepagents]'  # + tool_guard, governance middleware, skill loader
pip install 'palonexus[server]'      # + FastAPI host
pip install 'palonexus[all]'         # everything
```

## What's in the core

| Module | Purpose |
|---|---|
| `palonexus.client` | The `PaloNexus` facade (`from_env`, explicit ctor, `offline()`), `pn.agents`, `pn.audit`, `pn.revocation`, and the `pn.task(...)` context manager. |
| `palonexus.models` | The ten typed abstractions: `AgentIdentity`, `HumanOwner`, `Delegation`, `TaskSession`, `PolicyDecision`, `Credential`, `AuditEvent`, `Resource`, `AssetType` (+ `PolicyDecisionLog`). |
| `palonexus.errors` | The typed exception tree (`PolicyDenied`, `ApprovalRequired`, `DelegationExpired`, `CredentialRevoked`, `IdentityNotProvisioned`, `ControlPlaneUnavailable`, `GovernanceError`). |
| `palonexus.context` | `contextvars` + header propagation graduated from the `palonexus_agent` scaffold. |
| `palonexus.crypto` | Re-export of the standalone `agentdid` crypto primitive (ordinary dependency). |
| `palonexus.idp` | Re-export of the **vendored** `idp_sdk` HTTP client (formerly venv-only). |
| `palonexus.testing` | `FakeControlPlane` (deny-by-default, seeded Northstar personas), `run_hero_flow`, `SEED_SCENARIOS` — the offline seam (no network). |
| `palonexus.pytest_plugin` | Reusable fixtures `offline_pn`, `fake_control_plane`, `devops_personas` (auto-loaded via the `palonexus` pytest11 entry point). |
| `palonexus.langchain` | **REM-152** — `middleware(pn)` + `guarded_tool(...)`: gates tool calls via `/authz`, interrupts for approval or substitutes a deny `ToolMessage`. |
| `palonexus.langgraph` | **REM-153** — `governed_node(...)` + `resume_after_approval(pn)`: deny → `interrupt()` → approve → re-read, durable checkpointer required. |

`palonexus.langchain` (REM-152) and `palonexus.langgraph` (REM-153) are
implemented; `palonexus.deepagents` is the seam for REM-154. Each is importable on
a base install but requires its extra (`palonexus[langchain]` / `[langgraph]`) to
*use* — the lean-core / opt-in-weight contract (Appendix B.1). Runnable offline
examples live under [`examples/`](./examples/).

## Ten-minute first success (offline)

```python
from palonexus import PaloNexus, PolicyDenied, ApprovalRequired

pn = PaloNexus.offline()                              # no cluster needed
agent = pn.agents.register(
    name="northstar-devops-incident-agent",
    owner="ethan.park@northstar.example",             # mandatory (governance)
    sponsor="maya.chen@northstar.example",            # mandatory
    scenario="devops-incident",
)
agent.provision()

with pn.task(subject="ethan.park@northstar.example",
             task_id="INC-4821", scenario="devops-incident",
             actor="northstar-devops-incident-agent") as task:
    decision = task.check(action="runbooks:read",
                          resource="runbooks-api:/runbooks/db-failover")
    assert decision.needs_approval                    # deny-by-default until delegated
```

## Develop in the workspace

```bash
# from platform/ (the workspace root)
pip install -e ./agentdid -e ./idp-sdk -e './palonexus[test]'
cd palonexus && python -m pytest
mypy --strict src/palonexus
```

## Deny-by-default

Every governed failure mode is a typed exception. An unreachable decision point
raises `ControlPlaneUnavailable` — it is **never** swallowed into a silent allow.
