philcalc 0.1.0__tar.gz

philcalc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run --group dev pytest --cov=calc --cov-report=term-missing --cov-fail-under=90
+
+  smoke-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv tool install --force --reinstall --refresh .
+      - run: phil ':version'
+      - run: phil 'd(sin(x))/dx'

philcalc-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.DS_Store

philcalc-0.1.0/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS
+
+Guidance for human/AI contributors working in this repository.
+
+## Mission
+
+Keep `phil` accurate, safe, and fast to use for real math workflows in a terminal.
+
+## Non-Negotiables
+
+- Do not weaken parser safety (`GLOBAL_DICT`, blocked tokens, input limits).
+- Keep one-shot and REPL semantics aligned.
+- Keep output predictable for piping/scripts.
+- Add tests for every user-visible behavior change.
+
+## Preferred Workflow
+
+1. Implement smallest coherent change.
+2. Add/adjust tests (`unit`, `integration`, `regression`).
+3. Update docs (`README.md`, `DESIGN.md`, `KNOWLEDGE.md`, `CONTRIBUTOR.md`) if needed.
+4. Run:
+   - `uv run --group dev pytest`
+   - `uv run --group dev pytest --cov=calc --cov-report=term-missing --cov-fail-under=90`
+
+## Perfect Commit Protocol
+
+Use "perfect commit" discipline for every change:
+
+1. One logical change per commit.
+2. Commit must build, test, and run in isolation.
+3. Include tests for behavior changes or bug fixes.
+4. Include docs updates for user-visible changes.
+5. Keep unrelated refactors out of the same commit.
+
+Commit message format:
+
+- Subject: imperative, specific, <=72 chars.
+- Body: why this change exists, what changed, and user impact.
+- Footer (optional): issue/PR references.
+
+Suggested pre-commit gate:
+
+- `git diff --staged` is coherent and minimal.
+- tests pass locally for touched areas (or full suite for broad changes).
+
+## High-Value Areas
+
+- Parser normalization and syntax sugar (`df/dt`, relaxed input).
+- Error hint quality (`E:` + actionable `hint:`).
+- Matrix/ODE workflow ergonomics.
+- Formatting modes and copy/paste behavior.
+
+## Avoid
+
+- Hidden behavior that changes math semantics silently.
+- Implicit defaults when ambiguity exists (prefer explicit error + hint).
+- Breaking existing CLI flags without compatibility path.

philcalc-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-02-20
+
+- Initial public release.
+- Symbolic CLI calculator with exact arithmetic and core SymPy operations.
+- Hardened parser configuration and input guardrails.
+- Minimal terminal UX (`:h`, `:examples`, `:q`, `:x`) with actionable hints.
+- Optional WolframAlpha fallback hint on evaluation errors.
+- uv package layout, tests, and GitHub Actions CI.

philcalc-0.1.0/CONTRIBUTOR.md

@@ -0,0 +1,90 @@
+# Contributor Guide
+
+This project is a terminal-first symbolic calculator (`phil`) built on SymPy.
+Changes should improve correctness, safety, and practical UX for math workflows.
+
+## Development Setup
+
+```bash
+uv run --group dev pytest
+uv run phil '2+2'
+uv run phil
+```
+
+## Testing Strategy (Required)
+
+Run these before pushing:
+
+```bash
+uv run --group dev pytest
+uv run --group dev pytest --cov=calc --cov-report=term-missing --cov-fail-under=90
+```
+
+Test categories:
+
+- `unit`: pure behavior of parser/evaluator/format helpers.
+- `integration`: process-level CLI/REPL behavior.
+- `regression`: fixed bug cases that must never regress.
+
+Property tests (`hypothesis`) are used for high-value invariants in numeric/symbolic behavior.
+
+## Perfect Commit Standard
+
+Adopt a "perfect commit" bar:
+
+1. One logical change per commit.
+2. Commit is releasable on its own (no broken intermediate states).
+3. Tests accompany behavior changes.
+4. Docs accompany user-facing changes.
+5. Exclude unrelated cleanup from the same commit.
+
+Before committing:
+
+- Review staged diff only: `git diff --staged`
+- Verify tests:
+  - `uv run --group dev pytest`
+  - `uv run --group dev pytest --cov=calc --cov-report=term-missing --cov-fail-under=90`
+
+Commit message guidance:
+
+- Subject: imperative and specific, <=72 chars.
+- Body: explain why, summarize what changed, note user impact.
+
+## CI Expectations
+
+CI runs:
+
+- tests + coverage on Python `3.12` and `3.13`
+- install smoke test (`uv tool install .`, then run `phil`)
+
+If your change adds behavior, add/adjust tests in the correct category.
+
+## Adding or Changing Math Operations
+
+1. Add required import(s) in `src/calc/core.py`.
+2. Expose user-facing entry in `LOCALS_DICT`.
+3. Add tests in `tests/test_core.py` (and regression tests if bug-fix related).
+4. Update `README.md` and `KNOWLEDGE.md` if user-visible.
+5. Run full suite.
+
+## Safety Rules
+
+- Do not loosen parser globals in `GLOBAL_DICT`.
+- Keep blocked-token and input-size protections unless there is a measured reason.
+- Never execute user input outside SymPy parse/eval path.
+
+## UX Rules
+
+- Output remains terminal-first and script-friendly.
+- Errors are concise: `E:` + actionable `hint:`.
+- Keep REPL behavior consistent with one-shot mode (`--strict`, `--format`, `--no-simplify`).
+
+## Scope Guardrails
+
+Avoid unnecessary complexity:
+
+- plugin systems
+- unrelated persistence layers
+- large configuration frameworks
+
+When adding complexity, explain the user value and testing impact in the PR.

philcalc-0.1.0/DESIGN.md

@@ -0,0 +1,82 @@
+# Design & Implementation
+
+## Architecture
+
+```
+user input
+    ↓
+parse_expr()        ← controlled namespace + restricted globals
+    ↓
+SymPy expression
+    ↓
+simplify()          ← skipped for list/tuple/dict results
+    ↓
+print()
+```
+
+## Project layout
+
+```
+pyproject.toml
+src/calc/core.py    ← parser and evaluator
+src/calc/cli.py     ← command-line interface
+tests/test_core.py
+tests/test_cli.py
+phil                ← local launcher script (uv run --project)
+CONTRIBUTOR.md      ← contribution and extension guide
+```
+
+## Packaging model
+
+This project is a standard `uv` package:
+
+- `pyproject.toml` declares metadata and dependencies.
+- `[project.scripts]` exposes the `phil` command.
+- Tests run via `uv run --group dev pytest`.
+
+## Parsing model
+
+`parse_expr` is configured with:
+
+- Controlled `local_dict` (only the symbols and operations we allow)
+- Restricted `global_dict` with `__builtins__` removed
+- Transformations: `auto_number`, `factorial_notation`, `convert_xor`
+- Input validation before parsing (length and blocked-token checks)
+- Normalization pass for user-friendly syntax (`{}` -> `()`, `ln(` -> `log(`)
+
+This significantly reduces parser attack surface for CLI usage. It is still not a hardened sandbox for arbitrary untrusted multi-tenant input.
+
+By default, CLI evaluation uses relaxed parsing (`implicit_multiplication_application`) to make long calculator-style expressions easier to enter.
+`--strict` disables relaxed parsing in both one-shot and REPL modes.
+`--no-simplify` skips the simplify step for large or structure-sensitive expressions.
+
+`d(expr)` and `int(expr)` can infer the variable only when the expression has exactly one free symbol. Ambiguous or symbol-free expressions must pass the variable explicitly.
+REPL evaluation supports session locals, assignment (`name = expr`), and `ans` for last result.
+Matrix helpers are exposed in the allowed namespace (`Matrix`, `eye`, `zeros`, `ones`, `det`, `inv`, `rank`, `eigvals`).
+
+## Exit-code behavior
+
+- One-shot mode returns `0` on success.
+- One-shot mode returns `1` on parse/evaluation errors.
+- REPL mode keeps running on expression errors and exits `0` on Ctrl-C/Ctrl-D.
+
+## REPL UX
+
+- Prompt is `phil>`.
+- Minimal command mode inspired by terminal-first tools:
+  - `:h` or `:help` shows available commands
+  - `:examples` shows a compact learning set
+  - `:version` shows installed version
+  - `:update` / `:check` compare current vs latest version and print upgrade command
+  - `:q` or `:quit` exits
+- Errors are terse and prefixed with `E:`.
+- Common failures include contextual `hint:` lines.
+- Evaluation failures include a WolframAlpha URL hint for optional browser lookup.
+- Complex successful expressions also show a WolframAlpha equivalent hint.
+- `--wa` forces hints for all expressions; `--copy-wa` attempts clipboard copy.
+- Optional LaTeX output via `--latex`, `--latex-inline`, or `--latex-block`.
+- Optional output formats via `--format` (`plain`, `pretty`, `latex`, `latex-inline`, `latex-block`).
+
+## Startup time
+
+Startup cost is mostly from Python + SymPy import time. Packaging improves distribution/testing and reproducibility, but not raw import latency by itself.

philcalc-0.1.0/KNOWLEDGE.md

@@ -0,0 +1,56 @@
+# KNOWLEDGE
+
+Project-specific knowledge for contributors.
+
+## Product Surface
+
+- Distribution name: `philcalc`
+- CLI command: `phil`
+- Core module path: `src/calc/`
+
+## Parsing and Evaluation Model
+
+- Uses SymPy `parse_expr` with restricted globals.
+- Default mode is relaxed parsing for calculator-style input.
+- Strict mode (`--strict`) disables relaxed transforms.
+- Optional no-simplify mode (`--no-simplify`) returns parsed form without `simplify()`.
+
+## Supported Syntax Highlights
+
+- Derivative:
+  - `d(expr, var)`
+  - `d(expr)` when variable can be inferred uniquely
+  - Leibniz shorthand: `d(sin(x))/dx`, `df(t)/dt`
+- Integral:
+  - `int(expr, var)`
+  - `int(expr)` with unique variable inference
+- Matrix helpers:
+  - `Matrix`, `eye`, `zeros`, `ones`
+  - `det`, `inv`, `rank`, `eigvals`
+- Session behavior (REPL):
+  - assignment: `A = ...`
+  - `ans` = last result
+
+## Formatting Modes
+
+- `--format plain` (default)
+- `--format pretty`
+- `--format latex`
+- `--format latex-inline`
+- `--format latex-block`
+
+Legacy aliases:
+
+- `--latex`, `--latex-inline`, `--latex-block`
+
+## Error UX
+
+- Errors start with `E:`
+- Follow-up guidance via `hint:`
+- Syntax-specific hints exist for common derivative and matrix mistakes.
+
+## Testing Expectations
+
+- Unit + integration + regression tests.
+- Property tests via `hypothesis` for core invariants.
+- CI checks multiple Python versions and install smoke tests.

philcalc-0.1.0/LICENSE

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

philcalc-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: philcalc
+Version: 0.1.0
+Summary: Minimal symbolic CLI calculator powered by SymPy
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: sympy>=1.12
+Description-Content-Type: text/markdown
+
+# phil
+
+A minimal command-line calculator for exact arithmetic, symbolic differentiation, integration, algebraic equation solving, and ordinary differential equations.
+
+Powered by [SymPy](https://www.sympy.org/).
+
+## Install
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+Install from the project directory:
+
+```bash
+uv tool install .
+```
+
+Run without installing:
+
+```bash
+uv run phil '2+2'
+```
+
+## 60-Second Start
+
+```bash
+uv tool install .
+phil --help
+phil '1/3 + 1/6'
+phil '(1 - 25e^5)e^{-5t} + (25e^5 - 1)t e^{-5t} + t e^{-5t} ln(t)'
+phil
+```
+
+Then in REPL, try:
+
+1. `d(x^3 + 2*x, x)`
+2. `int(sin(x), x)`
+3. `solve(x^2 - 4, x)`
+
+## Usage
+
+### One-shot
+
+```bash
+phil '<expression>'
+phil --format pretty '<expression>'
+phil --no-simplify '<expression>'
+phil --latex '<expression>'
+phil --latex-inline '<expression>'
+phil --latex-block '<expression>'
+phil --wa '<expression>'
+phil --wa --copy-wa '<expression>'
+phil :examples
+```
+
+### Interactive
+
+```bash
+phil
+phil> <expression>
+```
+
+REPL commands:
+
+- `:h` / `:help` show help
+- `:examples` show sample expressions
+- `:v` / `:version` show current version
+- `:update` / `:check` compare current vs latest version and print update command
+- `:q` / `:quit` / `:x` exit
+
+The REPL starts with a short hint line and prints targeted `hint:` messages on common errors.
+Unknown `:` commands return a short correction hint.
+Evaluation errors also include: `hint: try WolframAlpha: <url>`.
+Complex expressions also print a WolframAlpha equivalent hint after successful evaluation.
+REPL sessions also keep `ans` (last result) and support assignment such as `A = Matrix([[1,2],[3,4]])`.
+
+### Help
+
+```bash
+phil --help
+```
+
+### Wolfram helper
+
+- By default, complex expressions print a WolframAlpha equivalent link.
+- Links are printed as full URLs for terminal auto-linking (including iTerm2).
+- Use `--wa` to always print the link.
+- Use `--copy-wa` to copy the link to your clipboard when shown.
+- Full URLs are usually clickable directly in modern terminals.
+
+## Updates
+
+From published package (anywhere):
+
+```bash
+uv tool upgrade philcalc
+```
+
+From a local clone of this repo:
+
+```bash
+uv tool install --force --reinstall --refresh .
+```
+
+Quick check in CLI:
+
+```bash
+phil :version
+phil :update
+phil :check
+```
+
+In REPL:
+
+- `:version` shows your installed version.
+- `:update`/`:check` show current version, latest known release, and update command.
+
+For release notifications on GitHub, use "Watch" -> "Custom" -> "Releases only" on the repo page.
+
+### Long Expressions (easier input)
+
+`phil` now uses relaxed parsing by default:
+
+- `2x` works like `2*x`
+- `{}` works like `()`
+- `ln(t)` works like `log(t)`
+
+So inputs like these work directly:
+
+```bash
+phil '(1 - 25e^5)e^{-5t} + (25e^5 - 1)t e^{-5t} + t e^{-5t} ln(t)'
+phil '(854/2197)e^{8t}+(1343/2197)e^{-5t}+((9/26)t^2 -(9/169)t)e^{8t}'
+```
+
+Use strict parsing if needed:
+
+```bash
+phil --strict '2*x'
+```
+
+## Examples
+
+```bash
+$ phil '1/3 + 1/6'
+1/2
+
+$ phil 'd(x^3 + 2*x, x)'
+3*x**2 + 2
+
+$ phil 'int(sin(x), x)'
+-cos(x)
+
+$ phil 'solve(x^2 - 4, x)'
+[-2, 2]
+
+$ phil 'N(pi, 30)'
+3.14159265358979323846264338328
+
+$ phil --latex 'd(x^2, x)'
+2 x
+
+$ phil --latex-inline 'd(x^2, x)'
+$2 x$
+
+$ phil --latex-block 'd(x^2, x)'
+$$
+2 x
+$$
+
+$ phil --format pretty 'Matrix([[1,2],[3,4]])'
+[1  2]
+[3  4]
+```
+
+## Test
+
+```bash
+uv run --group dev pytest
+```
+
+## GitHub
+
+- CI: `.github/workflows/ci.yml` runs tests on pushes and PRs.
+- License: MIT (`LICENSE`).
+- Ignore rules: Python/venv/cache (`.gitignore`).
+- Contribution guide: `CONTRIBUTOR.md`.
+
+## Learn by Doing
+
+Try this sequence in REPL mode:
+
+1. `1/3 + 1/6`
+2. `d(x^3 + 2*x, x)`
+3. `int(sin(x), x)`
+4. `solve(x^2 - 4, x)`
+5. `N(pi, 20)`
+
+If you get stuck, run `:examples` or `:h`.
+
+## Reference
+
+### Operations
+
+| Operation | Syntax |
+|-----------|--------|
+| Derivative | `d(expr, var)` |
+| Integral | `int(expr, var)` |
+| Solve equation | `solve(expr, var)` |
+| Solve ODE | `dsolve(Eq(...), func)` |
+| Equation | `Eq(lhs, rhs)` |
+| Numeric eval | `N(expr, digits)` |
+| Matrix determinant | `det(Matrix([[...]]))` |
+| Matrix inverse | `inv(Matrix([[...]]))` |
+| Matrix rank | `rank(Matrix([[...]]))` |
+| Matrix eigenvalues | `eigvals(Matrix([[...]]))` |
+
+### Symbols
+
+`x`, `y`, `z`, `t`, `pi`, `e`, `f`
+
+### Functions
+
+`sin`, `cos`, `tan`, `exp`, `log`, `sqrt`, `abs`
+
+### Matrix helpers
+
+`Matrix`, `eye`, `zeros`, `ones`, `det`, `inv`, `rank`, `eigvals`
+
+### Syntax notes
+
+- `^` is exponentiation (`x^2`)
+- `!` is factorial (`5!`)
+- relaxed mode (default) allows implicit multiplication (`2x`); use `--strict` to require `2*x`
+- `d(expr)` / `int(expr)` infer the variable when exactly one symbol is present
+- Leibniz shorthand is accepted: `d(sin(x))/dx`, `df(t)/dt`
+- `name = expr` assigns in REPL session (`ans` is always last result)
+- Undefined symbols raise an error
+
+## Safety limits
+
+- Expressions longer than 2000 chars are rejected.
+- Inputs containing blocked tokens like `__`, `;`, or newlines are rejected.
+
+See [DESIGN.md](DESIGN.md) for implementation details.