klongpy 0.7.0__tar.gz → 0.7.1__tar.gz

klongpy-0.7.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include MANIFEST.in
+recursive-include klongpy/lib *.kg

{klongpy-0.7.0/klongpy.egg-info → klongpy-0.7.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: klongpy
-Version: 0.7.0
+Version: 0.7.1
 Summary: High-Performance Klong array language with rich Python integration.
 Author: Brian Guarraci
 License-Expression: MIT
-Project-URL: Homepage, http://klongpy.org
+Project-URL: Homepage, https://klongpy.org
 Project-URL: Repository, https://github.com/briangu/klongpy
-Project-URL: Documentation, http://klongpy.org
+Project-URL: Documentation, https://klongpy.org
 Keywords: klong,array,language,interpreter,numpy,torch
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Interpreters
-Requires-Python: <3.13,>=3.9
+Requires-Python: <3.15,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=2.0
@@ -30,8 +30,8 @@ Requires-Dist: colorama==0.4.6; extra == "repl"
 Provides-Extra: web
 Requires-Dist: aiohttp==3.9.4; extra == "web"
 Provides-Extra: db
-Requires-Dist: pandas==2.2.2; extra == "db"
-Requires-Dist: duckdb==1.3.0; extra == "db"
+Requires-Dist: pandas==3.0.0; extra == "db"
+Requires-Dist: duckdb==1.4.4; extra == "db"
 Provides-Extra: ws
 Requires-Dist: websockets==12.0; extra == "ws"
 Provides-Extra: docs
@@ -41,8 +41,8 @@ Provides-Extra: all
 Requires-Dist: torch; extra == "all"
 Requires-Dist: colorama==0.4.6; extra == "all"
 Requires-Dist: aiohttp==3.9.4; extra == "all"
-Requires-Dist: pandas==2.2.2; extra == "all"
-Requires-Dist: duckdb==1.3.0; extra == "all"
+Requires-Dist: pandas==3.0.0; extra == "all"
+Requires-Dist: duckdb==1.4.4; extra == "all"
 Requires-Dist: websockets==12.0; extra == "all"
 Requires-Dist: mkdocs>=1.6; extra == "all"
 Requires-Dist: mkdocs-material>=9.7; extra == "all"
@@ -51,6 +51,8 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
 Requires-Dist: mkdocs>=1.6; extra == "dev"
 Requires-Dist: mkdocs-material>=9.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
 Dynamic: license-file
 
 
@@ -67,7 +69,14 @@ Dynamic: license-file
 
 # KlongPy: A High-Performance Array Language with Autograd
 
-KlongPy brings gradient-based programming to an already-succinct array language, so you can differentiate compact array expressions directly. It's also a batteries-included system with IPC, DuckDB-backed database tooling, web/websocket support, and other integrations exposed seamlessly from the language.
+KlongPy is a Python adaptation of the [Klong](https://t3x.org/klong) [array language](https://en.wikipedia.org/wiki/Array_programming), offering high-performance vectorized operations. It prioritizes compatibility with Python, thus allowing seamless integration of Python's expansive ecosystem while retaining Klong's succinctness.
+
+KlongPy backends include [NumPy](https://numpy.org/) and optional [PyTorch](https://pytorch.org/) (CPU, CUDA, and Apple MPS).
+When PyTorch is enabled, automatic differentiation (autograd) is supported; otherwise, numeric differentiation is the default.
+
+Full documentation: [https://klongpy.org](https://klongpy.org)
+
+New to v0.7.0, KlongPy now brings gradient-based programming to an already-succinct array language, so you can differentiate compact array expressions directly. It's also a batteries-included system with IPC, DuckDB-backed database tooling, web/websocket support, and other integrations exposed seamlessly from the language.
 
 Backends include NumPy and optional PyTorch (CPU, CUDA, and Apple MPS). When PyTorch is enabled, gradients use autograd; otherwise numeric differentiation is the default.
 
@@ -86,18 +95,11 @@ print(x)  # ~0
 
 **KlongPy gradient descent (2 lines):**
 ```klong
-f::{x^2}; x::5.0
-{x::x-(0.1*f:>x)}'!100   :" x -> 0
-```
-
-**Or with custom optimizer (copy from examples/):**
-```klong
-.pyf("optimizers";"SGDOptimizer")
-x::5.0; opt::SGDOptimizer(klong;["x"];:{["lr" 0.1]})
-{opt({x^2})}'!100        :" x -> 0
+f::{x^2}; s::5.0
+{s::s-(0.1*f:>s)}'!100   :" s -> 0"
 ```
 
-This isn't just shorter—it's a fundamentally different way to express computation. Array languages like APL, K, and Q revolutionized finance and data analysis with their concise vectorized operations. KlongPy adds native autograd, making gradients first-class citizens in an array language.
+Array languages like APL, K, and Q revolutionized finance by treating operations as data transformations, not loops. KlongPy brings this philosophy to machine learning: gradients become expressions you compose, not boilerplate you maintain. The result is a succint mathematical-like notation that is automatically extended to machine learning.
 
 ## Quick Install
 
@@ -108,27 +110,41 @@ kgpy
 
 # Enable torch backend (autograd + GPU)
 pip install "klongpy[torch]"
-USE_TORCH=1 kgpy            # or KLONGPY_BACKEND=torch
+kgpy --backend torch
 
 # Everything (web, db, websockets, torch, repl)
 pip install "klongpy[all]"
 ```
 
+## REPL
+
+```bash
+$ kgpy
+Welcome to KlongPy REPL v0.7.0
+Author: Brian Guarraci
+Web: http://klongpy.org
+Backend: torch (mps)
+]h for help; Ctrl-D or ]q to quit
+
+$>
+```
+
 ## Why KlongPy?
 
 ### For Quants and Traders
 
-Build self-learning trading strategies in a language designed for time series:
+Optimize portfolios with gradients in a language designed for arrays:
 
 ```klong
-:" Moving average crossover with learned parameters
-sma::{(+/x)%#x}
-signal::{(sma(n#x))-(sma(m#x))}  :" Difference of moving averages
-loss::{+/(signal(prices)-returns)^2}
-
-:" Learn optimal window sizes via gradient descent
-loss:>n                           :" Gradient w.r.t. short window
-loss:>m                           :" Gradient w.r.t. long window
+:" Portfolio optimization: gradient of Sharpe ratio"
+returns::[0.05 0.08 0.03 0.10]      :" Annual returns per asset"
+vols::[0.15 0.20 0.10 0.25]         :" Volatilities per asset"
+w::[0.25 0.25 0.25 0.25]            :" Portfolio weights"
+
+sharpe::{(+/x*returns)%((+/((x^2)*(vols^2)))^0.5)}
+sg::sharpe:>w                       :" Gradient of Sharpe ratio"
+.d("sharpe gradient="); .p(sg)
+sharpe gradient=[0.07257738709449768 0.032256484031677246 0.11693036556243896 -0.22176480293273926]
 ```
 
 ### For ML Researchers
@@ -136,13 +152,18 @@ loss:>m                           :" Gradient w.r.t. long window
 Neural networks in pure array notation:
 
 ```klong
-:" Single layer: sigmoid(W*x + b)
+:" Single-layer neural network with gradient descent"
+.bkf(["exp"])
 sigmoid::{1%(1+exp(0-x))}
 forward::{sigmoid((w1*x)+b1)}
-loss::{+/(forward'X - Y)^2}
+X::[0.5 1.0 1.5 2.0]; Y::[0.2 0.4 0.6 0.8]
+w1::0.1; b1::0.1; lr::0.1
+loss::{+/((forward'X)-Y)^2}
 
-:" Train with multi-param gradients
+:" Train with multi-param gradients"
 {grads::loss:>[w1 b1]; w1::w1-(lr*grads@0); b1::b1-(lr*grads@1)}'!1000
+.d("w1="); .d(w1); .d(" b1="); .p(b1)
+w1=1.74 b1=-2.17
 ```
 
 ### For Scientists
@@ -150,9 +171,10 @@ loss::{+/(forward'X - Y)^2}
 Express mathematics directly:
 
 ```klong
-:" Gradient of f(x,y,z) = x^2 + y^2 + z^2 at [1,2,3]
+:" Gradient of f(x,y,z) = x^2 + y^2 + z^2 at [1,2,3]"
 f::{+/x^2}
-f:>[1 2 3]    :" [2 4 6] - exact gradient via autograd
+f:>[1 2 3]
+[2.0 4.0 6.0]
 ```
 
 ## The Array Language Advantage
@@ -174,9 +196,33 @@ KlongPy inherits from the [APL](https://en.wikipedia.org/wiki/APL_(programming_l
 
 ## Performance: NumPy vs PyTorch Backend
 
-The PyTorch backend provides significant speedups for large arrays with GPU acceleration:
+The PyTorch backend provides significant speedups for large arrays with GPU acceleration (RTX 4090 in this case):
+
+```
+$ python3 tests/perf_vector.py
+============================================================
+VECTOR OPS (element-wise, memory-bound)
+  Size: 10,000,000 elements, Iterations: 100
+============================================================
+NumPy (baseline)                    0.021854s
+KlongPy (numpy)                     0.001413s  (15.46x vs NumPy)
+KlongPy (torch, cpu)                0.000029s  (761.22x vs NumPy)
+KlongPy (torch, cuda)               0.000028s  (784.04x vs NumPy)
+
+============================================================
+MATRIX MULTIPLY (compute-bound, GPU advantage)
+  Size: 4000x4000, Iterations: 5
+============================================================
+NumPy (baseline)                    0.078615s
+KlongPy (numpy)                     0.075400s  (1.04x vs NumPy)
+KlongPy (torch, cpu)                0.077350s  (1.02x vs NumPy)
+KlongPy (torch, cuda)               0.002339s  (33.62x vs NumPy)
+```
+
+Also supporting Apple Silicon MPS (M1 Mac Studio) enables fast local work:
 
 ```
+$ python tests/perf_backend.py --compare
 Benchmark                   NumPy (ms)   Torch (ms)      Speedup
 ----------------------------------------------------------------------
 vector_add_1M                    0.327        0.065    5.02x (torch)
@@ -186,11 +232,9 @@ grade_up_100K                    0.588        0.199    2.96x (torch)
 enumerate_1M                     0.141        0.050    2.83x (torch)
 ```
 
-*Benchmarks on Apple M1 with MPS. Run `python tests/perf_backend.py --compare` for your system.*
-
 ## Complete Feature Set
 
-KlongPy isn't just an autograd experiment—it's a production-ready platform with kdb+/Q-inspired features:
+KlongPy is a batteries-included platform with kdb+/Q-inspired features:
 
 ### Core Language
 - **Vectorized Operations**: NumPy/PyTorch-powered bulk array operations
@@ -230,8 +274,8 @@ KlongPy uses Unicode operators for mathematical notation. Here's how to type the
 
 **Alternative:** Use the function equivalents that don't require special characters:
 ```klong
-3∇f           :" Using nabla
-.jacobian(f;x) :" Instead of x∂f
+3∇f           :" Using nabla"
+.jacobian(f;x) :" Instead of x∂f"
 ```
 
 ## Syntax Cheat Sheet
@@ -239,39 +283,40 @@ KlongPy uses Unicode operators for mathematical notation. Here's how to type the
 Functions take up to 3 parameters, always named `x`, `y`, `z`:
 
 ```klong
-:" Operators (right to left evaluation)
-5+3*2           :" 11 (3*2 first, then +5)
-+/[1 2 3]       :" 6  (sum: + over /)
-*/[1 2 3]       :" 6  (product: * over /)
-#[1 2 3]        :" 3  (length)
-|[3 1 2]        :" [1 2 3] (sort)
-&[1 0 1]        :" [0 2] (where/indices of true)
-
-:" Functions
-avg::{(+/x)%#x}         :" Monad (1 arg)
-dot::{+/x*y}            :" Dyad (2 args)
-clip::{x|y&z}           :" Triad (3 args): min(max(x,y),z)
-
-:" Adverbs (modifiers)
-f'[1 2 3]               :" Each: apply f to each element
-1 2 3 +'[10 20 30]      :" Each-pair: [11 22 33]
-+/[1 2 3]               :" Over: fold/reduce
-+\[1 2 3]               :" Scan: running fold [1 3 6]
-
-:" Autograd
+:" Operators (right to left evaluation)"
+5+3*2           :" 11 (3*2 first, then +5)"
++/[1 2 3]       :" 6  (sum: + over /)"
+*/[1 2 3]       :" 6  (product: * over /)"
+#[1 2 3]        :" 3  (length)"
+3|5             :" 5  (max)"
+3&5             :" 3  (min)"
+
+:" Functions"
+avg::{(+/x)%#x}         :" Monad (1 arg)"
+dot::{+/x*y}            :" Dyad (2 args)"
+clip::{(x|y)&z}         :" Triad (3 args): min(max(x,y),z)"
+
+:" Adverbs (modifiers)"
+f::{x^2}
+f'[1 2 3]               :" Each: apply f to each -> [1 4 9]"
++/[1 2 3]               :" Over: fold/reduce -> 6"
++\[1 2 3]               :" Scan: running fold -> [1 3 6]"
+
+:" Autograd"
 f::{x^2}
-3∇f                     :" Numeric gradient at x=3 -> ~6.0
-f:>3                    :" Autograd (exact with torch) at x=3 -> 6.0
-f:>[1 2 3]              :" Gradient of sum-of-squares -> [2 4 6]
+3∇f                     :" Numeric gradient at x=3 -> ~6.0"
+f:>3                    :" Autograd (exact with torch) at x=3 -> 6.0"
+f::{+/x^2}             :" Redefine f as sum-of-squares"
+f:>[1 2 3]              :" Gradient -> [2 4 6]"
 
-:" Multi-parameter gradients
+:" Multi-parameter gradients"
 w::2.0; b::3.0
 loss::{(w^2)+(b^2)}
-loss:>[w b]             :" Gradients for both -> [4.0 6.0]
+loss:>[w b]             :" Gradients for both -> [4.0 6.0]"
 
-:" Jacobian (for vector functions)
-g::{x^2}                :" Element-wise square
-[1 2]∂g                 :" Jacobian matrix -> [[2 0] [0 4]]
+:" Jacobian (for vector functions)"
+g::{x^2}                :" Element-wise square"
+[1 2]∂g                 :" Jacobian matrix -> [[2 0] [0 4]]"
 ```
 
 ## Examples
@@ -281,13 +326,13 @@ g::{x^2}                :" Element-wise square
 ```klong
 ?> a::[1 2 3 4 5]
 [1 2 3 4 5]
-?> a*a                    :" Element-wise square
+?> a*a                    :" Element-wise square"
 [1 4 9 16 25]
-?> +/a                    :" Sum
+?> +/a                    :" Sum"
 15
-?> (*/a)                  :" Product
+?> (*/a)                  :" Product"
 120
-?> avg::{(+/x)%#x}        :" Define average
+?> avg::{(+/x)%#x}        :" Define average"
 :monad
 ?> avg(a)
 3.0
@@ -295,43 +340,49 @@ g::{x^2}                :" Element-wise square
 
 ### 2. Gradient Descent
 
+Minimize f(x) = (x-3)^2
+
+(with PyTorch's autograd)
 ```klong
-:" Minimize f(x) = (x-3)^2
+$ rlwrap kgpy --backend torch
 ?> f::{(x-3)^2}
 :monad
-?> x::10.0; lr::0.1
+?> s::10.0; lr::0.1
 0.1
-?> {x::x-(lr*f:>x); x}'!10    :" 10 gradient steps
-[8.6 7.48 6.584 5.867 5.294 4.835 4.468 4.175 3.940 3.752]
+?> {s::s-(lr*f:>s); s}'!10
+[8.600000381469727 7.4800004959106445 6.584000587463379 5.8672003746032715 5.293760299682617 4.835008144378662 4.468006610870361 4.174405097961426 3.9395241737365723 3.751619338989258]
+```
+
+(Numerical differentiation)
+```klong
+$ rlwrap kgpy
+?> f::{(x-3)^2}
+:monad
+?> s::10.0; lr::0.1
+0.1
+?> {s::s-(lr*f:>s); s}'!10
+[8.60000000104776 7.480000001637279 6.584000001220716 5.867200000887465 5.2937600006031005 4.835008000393373 4.4680064002611175 4.174405120173077 3.939524096109306 3.7516192768605094]
 ```
 
 ### 3. Linear Regression
 
 ```klong
-:" Data: y = 2*x + 3 + noise
+:" Data: y = 2*x + 3 + noise"
 X::[1 2 3 4 5]
 Y::[5.1 6.9 9.2 10.8 13.1]
 
-:" Model parameters
+:" Model parameters"
 w::0.0; b::0.0
 
-:" Loss function
+:" Loss function"
 mse::{(+/(((w*X)+b)-Y)^2)%#X}
 
-:" Train with multi-parameter gradients
+:" Train with multi-parameter gradients"
 lr::0.01
 {grads::mse:>[w b]; w::w-(lr*grads@0); b::b-(lr*grads@1)}'!1000
 
 .d("Learned: w="); .d(w); .d(" b="); .p(b)
-:" Output: Learned: w=2.02 b=2.94
-```
-
-**Or with custom optimizer (copy from examples/autograd/optimizers.py):**
-```klong
-.pyf("optimizers";"AdamOptimizer")
-w::0.0; b::0.0
-opt::AdamOptimizer(klong;["w" "b"];:{["lr" 0.01]})
-{opt(mse)}'!1000         :" Optimizer handles gradient computation
+Learned: w=2.01 b=2.97
 ```
 
 ### 4. Database Operations
@@ -362,11 +413,11 @@ Carol  35
 
 **Client:**
 ```klong
-?> f::.cli(8888)              :" Connect to server
+?> f::.cli(8888)              :" Connect to server"
 remote[localhost:8888]:fn
-?> myavg::f(:avg)             :" Get remote function reference
+?> myavg::f(:avg)             :" Get remote function reference"
 remote[localhost:8888]:fn:avg:monad
-?> myavg(!1000000)            :" Execute on server
+?> myavg(!1000000)            :" Execute on server"
 499999.5
 ```
 
@@ -402,7 +453,7 @@ pip install "klongpy[repl]"
 ### With PyTorch Autograd (Recommended)
 ```bash
 pip install "klongpy[torch]"
-USE_TORCH=1 kgpy              # Enable torch backend (or KLONGPY_BACKEND=torch)
+kgpy --backend torch          # Enable torch backend
 ```
 
 ### Web / DB / WebSockets Extras
@@ -428,7 +479,7 @@ KlongPy stands on the shoulders of giants:
 - **[NumPy](https://numpy.org/)**: The "Iverson Ghost" in Python's scientific stack
 - **[PyTorch](https://pytorch.org/)**: Automatic differentiation and GPU acceleration
 
-KlongPy combines Klong's simplicity with Python's ecosystem and PyTorch's autograd—creating something new: an array language where gradients are first-class citizens.
+KlongPy combines Klong's simplicity with Python's ecosystem and PyTorch's autograd creating something new: an array language where gradients are first-class citizens.
 
 ## Use Cases
 
@@ -466,7 +517,7 @@ python3 -m pytest tests/  # Run tests
 
 This project does not accept direct issue submissions.
 
-Please start with a GitHub Discussion.  
+Please start with a GitHub Discussion.
 Maintainers will promote validated discussions to Issues.
 
 Active contributors may be invited to open issues directly.