Metadata-Version: 2.4
Name: physicsos
Version: 0.1.16
Summary: AI-native physics simulation OS with TAPS-first physics IR, solver planning, and cloud runner tooling.
Project-URL: Homepage, https://github.com/fzj1214/PhysicsOS
Project-URL: Repository, https://github.com/fzj1214/PhysicsOS
Project-URL: Documentation, https://github.com/fzj1214/PhysicsOS/blob/main/ARCHITECTURE.md
Keywords: physics,simulation,pde,fem,agents,neural-operator
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.7
Requires-Dist: numpy>=1.26
Requires-Dist: deepagents
Requires-Dist: deepagents-cli>=0.0.46
Requires-Dist: langgraph
Requires-Dist: langchain-openai
Requires-Dist: rich>=13.7
Requires-Dist: gmsh>=4.13
Requires-Dist: meshio>=5.3
Provides-Extra: agents
Provides-Extra: geometry
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: all

# PhysicsOS

PhysicsOS is an AI-native physics simulation scaffold built around a TAPS-first workflow:

- compile physics problems into typed weak-form / solver IR;
- route executable IR blocks to local TAPS kernels;
- prepare audited fallback bundles for FEniCSx, MFEM, PETSc, or cloud runners;
- expose a CLI for PhysicsOS Cloud / foamvm device-login and job submission.

The project is currently alpha-stage research infrastructure. Local TAPS kernels are intentionally lightweight and deterministic; full-solver execution is prepared through manifests and approval gates rather than silently running external software.

## Install

From a local checkout:

```bash
pip install -e .
```

The default install includes the official DeepAgents CLI/TUI, LangGraph, and the OpenAI-compatible model adapter, so `physicsos` starts the natural-language PhysicsOS agent loop immediately after model credentials are configured.

With Gmsh / meshio geometry tooling:

```bash
pip install -e ".[geometry]"
```

For package build and test tooling:

```bash
pip install -e ".[dev]"
```

## CLI

```bash
physicsos
physicsos paths
physicsos auth login
physicsos account
physicsos runner submit path/to/manifest.json
physicsos runner status JOB_ID
physicsos runner logs JOB_ID
physicsos runner artifacts JOB_ID
```

Running `physicsos` with no arguments launches the official DeepAgents Textual TUI with the `physicsos` agent selected.
PhysicsOS automatically installs its DeepAgents agent prompt and subagent prompts under `~/.deepagents/physicsos/`.
DeepAgents manages interactive threads, TUI state, model selection, MCP tools, skills, and approval prompts.
PhysicsOS local control commands remain available as normal shell commands, for example `physicsos paths`, `physicsos auth login`, and `physicsos runner ...`.
Device-login tokens are stored under the user config directory, not in the repository.

To enable model calls, configure an OpenAI-compatible model:

```powershell
$env:PHYSICSOS_OPENAI_API_KEY="..."
$env:PHYSICSOS_OPENAI_BASE_URL="https://api.tu-zi.com/v1"
$env:PHYSICSOS_OPENAI_MODEL="gpt-5.4"
```

These variables are mapped to the official DeepAgents CLI at startup. You can still pass native DeepAgents flags through `physicsos`, for example:

```bash
physicsos --message "simulate a 1D steady heat conduction problem"
physicsos --resume
physicsos --model openai:gpt-5.4
```

## Local Data

PhysicsOS uses `PHYSICSOS_HOME` when set. Otherwise, pip-installed usage stores runtime state under:

```text
~/.physicsos/
```

In a source checkout, runtime artifacts stay under the repository so tests and development remain reproducible.

Default paths:

- Unified config: `~/.physicsos/config.json`
- Cloud auth config: `~/.physicsos/config.json` under the `cloud` object
- Interactive sessions: `~/.physicsos/sessions/session-*.jsonl` for pip installs, or `./sessions/session-*.jsonl` in a source checkout
- Command history: `~/.physicsos/history.jsonl` for pip installs, or `./history.jsonl` in a source checkout
- Solver/session artifacts: `~/.physicsos/scratch/...` for pip installs, or `./scratch/...` in a source checkout
- Case memory: `~/.physicsos/data/case_memory.jsonl` for pip installs, or `./data/case_memory.jsonl` in a source checkout
- Knowledge base: `~/.physicsos/data/knowledge/physicsos_knowledge.sqlite` for pip installs, or `./data/knowledge/physicsos_knowledge.sqlite` in a source checkout

Set `PHYSICSOS_HOME=/path/to/physicsos-home` to relocate these files.
Run `physicsos paths` to print the exact paths used by the current environment.

## Config

PhysicsOS creates `~/.physicsos/config.json` on first run. Edit it to set model, API, cloud, and storage preferences in one place:

```json
{
  "model": {
    "provider": "openai",
    "name": "gpt-5.4",
    "api_key": "",
    "base_url": "https://api.tu-zi.com/v1",
    "use_responses_api": false
  },
  "cloud": {
    "runner_url": "https://foamvm.vercel.app",
    "access_token": ""
  }
}
```

Environment variables such as `PHYSICSOS_OPENAI_API_KEY`, `PHYSICSOS_OPENAI_BASE_URL`, and `PHYSICSOS_OPENAI_MODEL` still override this file for one-off runs.

## Development

```bash
python -B -m pytest -q
python -m build
python -m twine check dist/*
```

## Notes

- `ARCHITECTURE.md` is the main design document.
- `taps.md` describes the TAPS-first solver strategy.
- `vm.md` describes PhysicsOS Cloud / foamvm integration.
- Heavy model weights, generated scratch artifacts, local secrets, and knowledge databases are excluded from package distribution.
