npcpy 1.2.36__py3-none-any.whl → 1.2.37__py3-none-any.whl

{npcpy-1.2.36.dist-info → npcpy-1.2.37.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcpy
-Version: 1.2.36
+Version: 1.2.37
 Summary: npcpy is the premier open-source library for integrating LLMs and Agents into python systems.
 Home-page: https://github.com/NPC-Worldwide/npcpy
 Author: Christopher Agostino
@@ -607,6 +607,178 @@ else:
 The intention for this model ensembler system is to mimic human cognition: pattern-matched gut reactions (System 1 of Kahneman) for familiar queries, falling back to deliberate reasoning (System 2 of Kahneman) for novel problems. Genetic algorithms evolve both knowledge structures and model specializations over time.
 
 
+## NPCArray - NumPy for AI
+
+`npcpy` provides `NPCArray`, a NumPy-like interface for working with populations of models (LLMs, sklearn, PyTorch) at scale. Think of it as vectorized operations over AI models.
+
+### Core Concepts
+- Model arrays support vectorized operations
+- Operations are lazy until `.collect()` is called (like Spark)
+- Same interface works for single models (treated as length-1 arrays)
+- Supports ensemble voting, consensus, evolution, and more
+
+### Basic Usage
+
+```python
+from npcpy.npc_array import NPCArray
+
+# Create array of LLMs
+models = NPCArray.from_llms(
+    ['llama3.2', 'gemma3:1b'],
+    providers='ollama'
+)
+
+print(f"Model array shape: {models.shape}")  # (2,)
+
+# Inference across all models - returns shape (n_models, n_prompts)
+result = models.infer("What is 2+2? Just the number.").collect()
+
+print(f"Model 1: {result.data[0, 0]}")
+print(f"Model 2: {result.data[1, 0]}")
+```
+
+### Lazy Chaining & Ensemble Operations
+
+```python
+from npcpy.npc_array import NPCArray
+
+models = NPCArray.from_llms(['llama3.2', 'gemma3:1b', 'mistral:7b'])
+
+# Build lazy computation graph - nothing executed yet
+result = (
+    models
+    .infer("Is Python compiled or interpreted? One word.")
+    .map(lambda r: r.strip().lower())  # Clean responses
+    .vote(axis=0)  # Majority voting across models
+)
+
+# Show the computation plan
+result.explain()
+
+# Now execute
+answer = result.collect()
+print(f"Consensus: {answer.data[0]}")
+```
+
+### Parameter Sweeps with Meshgrid
+
+```python
+from npcpy.npc_array import NPCArray
+
+# Cartesian product over parameters
+configs = NPCArray.meshgrid(
+    models=['llama3.2', 'gemma3:1b'],
+    temperatures=[0.0, 0.5, 1.0]
+)
+
+print(f"Config array shape: {configs.shape}")  # (6,) = 2 models × 3 temps
+
+# Run inference with each config
+result = configs.infer("Complete: The quick brown fox").collect()
+```
+
+### Matrix Sampling with get_llm_response
+
+The `get_llm_response` function supports `matrix` and `n_samples` parameters for exploration:
+
+```python
+from npcpy.llm_funcs import get_llm_response
+
+# Matrix parameter - cartesian product over specified params
+result = get_llm_response(
+    "Write a creative opening line.",
+    matrix={
+        'model': ['llama3.2', 'gemma3:1b'],
+        'temperature': [0.5, 1.0]
+    }
+)
+print(f"Number of runs: {len(result['runs'])}")  # 4 = 2×2
+
+# n_samples - multiple samples from same config
+result = get_llm_response(
+    "Pick a random number 1-100.",
+    model='llama3.2',
+    n_samples=5
+)
+print(f"Samples: {[r['response'] for r in result['runs']]}")
+
+# Combine both for full exploration
+result = get_llm_response(
+    "Flip a coin: heads or tails?",
+    matrix={'model': ['llama3.2', 'gemma3:1b']},
+    n_samples=3  # 2 models × 3 samples = 6 runs
+)
+```
+
+### sklearn Integration
+
+```python
+from npcpy.npc_array import NPCArray
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.linear_model import LogisticRegression
+import numpy as np
+
+# Create sample data
+X_train = np.random.randn(100, 4)
+y_train = (X_train[:, 0] > 0).astype(int)
+
+# Pre-fit models
+rf = RandomForestClassifier(n_estimators=10).fit(X_train, y_train)
+lr = LogisticRegression().fit(X_train, y_train)
+
+# Create array from fitted models
+models = NPCArray.from_sklearn([rf, lr])
+
+# Vectorized prediction
+X_test = np.random.randn(20, 4)
+predictions = models.predict(X_test).collect()
+
+print(f"RF predictions: {predictions.data[0]}")
+print(f"LR predictions: {predictions.data[1]}")
+```
+
+### ML Functions with Grid Search
+
+```python
+from npcpy.ml_funcs import fit_model, score_model, ensemble_predict
+
+# Grid search via matrix parameter
+result = fit_model(
+    X_train, y_train,
+    model='RandomForestClassifier',
+    matrix={
+        'n_estimators': [10, 50, 100],
+        'max_depth': [3, 5, 10]
+    }
+)
+
+print(f"Fitted {len(result['models'])} model configurations")
+
+# Ensemble voting with multiple models
+predictions = ensemble_predict(X_test, result['models'], method='vote')
+```
+
+### Quick Utilities
+
+```python
+from npcpy.npc_array import infer_matrix, ensemble_vote
+
+# Quick matrix inference
+result = infer_matrix(
+    prompts=["Hello", "Goodbye"],
+    models=['llama3.2', 'gemma3:1b']
+)
+
+# Quick ensemble vote
+answer = ensemble_vote(
+    "What is the capital of France? One word.",
+    models=['llama3.2', 'gemma3:1b']
+)
+print(f"Voted answer: {answer}")
+```
+
+See `examples/npc_array_examples.py` for more comprehensive examples.
+
 
 ## Serving an NPC Team
 

{npcpy-1.2.36.dist-info → npcpy-1.2.37.dist-info}/RECORD

@@ -1,10 +1,12 @@
-npcpy/__init__.py,sha256=9imxFtK74_6Rw9rz0kyMnZYl_voPb569tkTlYLt0Urg,131
-npcpy/llm_funcs.py,sha256=RtZAtX1_nvfn-X3IHVyQggDBXDzGxKEix_sS_iliNN0,87172
+npcpy/__init__.py,sha256=uJcJGjR1mWvE69GySNAufkgiRwJA28zdObDBWaxp0tY,505
+npcpy/llm_funcs.py,sha256=KJpjN6q5iW_qdUfgt4tzYENCAu86376io8eFZ7wp76Y,78081
 npcpy/main.py,sha256=RWoRIj6VQLxKdOKvdVyaq2kwG35oRpeXPvp1CAAoG-w,81
-npcpy/npc_compiler.py,sha256=mMYokNIlROl10NKsLJA_4wgO5rRr6tJQNRUwM13cnx8,101078
-npcpy/npc_sysenv.py,sha256=t9AswM-9_P2NaGsnlzTMc2hUfdSthi9ofbud6F1G7LM,35974
+npcpy/ml_funcs.py,sha256=UI7k7JR4XOH_VXR-xxLaO4r9Kyx_jBaEnp3TUIY7ZLQ,22657
+npcpy/npc_array.py,sha256=fVTxcMiXV-lvltmuwaRnTU9D3ikPq3-7k5wzp7MA5OY,40224
+npcpy/npc_compiler.py,sha256=oGSn9-X-Miq-K37QfNo8_TFcWbOl8WTNHBPtkf6paws,104619
+npcpy/npc_sysenv.py,sha256=rtE3KrXvIuOEpMq1CW5eK5K0o3f6mXagNXCeMnhHob4,36736
 npcpy/npcs.py,sha256=eExuVsbTfrRobTRRptRpDm46jCLWUgbvy4_U7IUQo-c,744
-npcpy/serve.py,sha256=3QU62spZ-yyWqWYb1iV_22Ir7shqMUSH_TKhvt8Ljkw,169725
+npcpy/serve.py,sha256=wbIXUFlmfKg72ZYoX_cBJ8FVDFabHsGnbMwMIj-412Y,174839
 npcpy/tools.py,sha256=A5_oVmZkzGnI3BI-NmneuxeXQq-r29PbpAZP4nV4jrc,5303
 npcpy/data/__init__.py,sha256=1tcoChR-Hjn905JDLqaW9ElRmcISCTJdE7BGXPlym2Q,642
 npcpy/data/audio.py,sha256=3qryGXnWHa4JFMonjuX-lf0fCrF8jmbHe7mHAuOdua0,12397
@@ -25,9 +27,9 @@ npcpy/ft/usft.py,sha256=O025GGYGZQf2ZVLowyAmBwh5bJyuy2dUAM6v03YcboY,3435
 npcpy/gen/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 npcpy/gen/audio_gen.py,sha256=w4toESu7nmli1T5FOwRRCGC_QK9W-SMWknYYkbRv9jE,635
 npcpy/gen/embeddings.py,sha256=QStTJ2ELiC379OEZsLEgGGIIFD267Y8zQchs7HRn2Zg,2089
-npcpy/gen/image_gen.py,sha256=PFaJAjMB0P1DV_x4tWXh25qGyjkntRejFLBnVPKSsqY,21730
+npcpy/gen/image_gen.py,sha256=VflU_wJsKWJarOVwZtL2M8ymDFfKNz8WX66Rwk4obeo,21778
 npcpy/gen/ocr.py,sha256=rgmXWHrCYX1Po-qG_LrNFbVYEZ8aaupxFTgparcoB_Y,6554
-npcpy/gen/response.py,sha256=6iAOi4hxUxkTZ1d2suBUASOssT6pQnr3HFwZWrvmATg,31925
+npcpy/gen/response.py,sha256=xSFHNZTDsebFo_nptWwSahpCU9_4pbCqabMFZ3X4_Bg,39979
 npcpy/gen/video_gen.py,sha256=RFi3Zcq_Hn3HIcfoF3mijQ6G7RYFZaM_9pjPTh-8E64,3239
 npcpy/memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 npcpy/memory/command_history.py,sha256=vWzZ4F4o0XOSHn50SkdP885jG1aZIZvfcPAh8EZWlQk,54497
@@ -42,14 +44,14 @@ npcpy/sql/ai_function_tools.py,sha256=ZCpjVHtaMRdL2dXxbQy5NhhjtPrVViGT1wyEl8ADrk
 npcpy/sql/database_ai_adapters.py,sha256=CMlNGOhmJZhGB47RPvLIMqB61m_eYPVg1lwx42_b0jQ,6865
 npcpy/sql/database_ai_functions.py,sha256=XQCmaFOE1lNCnwrLTNpotYOlv6sx41bb8hxZI_sqpy8,6335
 npcpy/sql/model_runner.py,sha256=hJZ7hx2mwI-8DAh47Q6BwOsRjx30-HzebL4ajEUO4HA,5734
-npcpy/sql/npcsql.py,sha256=-PmV7AXSKwRog4gPHTeHzmvPrnDZOiccjgkUGv4DwEU,35614
+npcpy/sql/npcsql.py,sha256=YRBbcsMPNWLhzZqoF0wAL2MaT6OOc0wh33Z0hb01rjc,36591
 npcpy/sql/sql_model_compiler.py,sha256=G-0dpTlgzc-dXy9YEsdWGjO8xaQ3jFNbc6oUja1Ef4M,5364
 npcpy/work/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 npcpy/work/desktop.py,sha256=F3I8mUtJp6LAkXodsh8hGZIncoads6c_2Utty-0EdDA,2986
 npcpy/work/plan.py,sha256=QyUwg8vElWiHuoS-xK4jXTxxHvkMD3VkaCEsCmrEPQk,8300
 npcpy/work/trigger.py,sha256=P1Y8u1wQRsS2WACims_2IdkBEar-iBQix-2TDWoW0OM,9948
-npcpy-1.2.36.dist-info/licenses/LICENSE,sha256=j0YPvce7Ng9e32zYOu0EmXjXeJ0Nwawd0RA3uSGGH4E,1070
-npcpy-1.2.36.dist-info/METADATA,sha256=TclDTn6w0nbPuQXtbOTFwxfpHVgjYYc49EVDHTiMW64,33537
-npcpy-1.2.36.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-npcpy-1.2.36.dist-info/top_level.txt,sha256=g1pbSvrOOncB74Bg5-J0Olg4V0A5VzDw-Xz5YObq8BU,6
-npcpy-1.2.36.dist-info/RECORD,,
+npcpy-1.2.37.dist-info/licenses/LICENSE,sha256=j0YPvce7Ng9e32zYOu0EmXjXeJ0Nwawd0RA3uSGGH4E,1070
+npcpy-1.2.37.dist-info/METADATA,sha256=xviLiFxgZ1uK876GGrIIm-P3uEJlwBvCtbbgn0vFUP4,37940
+npcpy-1.2.37.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+npcpy-1.2.37.dist-info/top_level.txt,sha256=g1pbSvrOOncB74Bg5-J0Olg4V0A5VzDw-Xz5YObq8BU,6
+npcpy-1.2.37.dist-info/RECORD,,