Merge pull request #160 from NPC-Worldwide/chris/alicanto_knowledge_graph_upgrades

Chris/alicanto knowledge graph upgrades

Author: cagostino

.gitignore

@@ -26,3 +26,5 @@ __pycache__/
 *.gz
 *.tgz
 .vscode/mcp.json
+.vscode/settings.json
+.build.py

README.md

@@ -1,4 +1,3 @@
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy.png" alt="npcpy logo of a solarpunk sign">
 </p>
@@ -102,8 +101,98 @@ handling agent pass
 {'debrief': {'summary': "The responses provided detailed accounts of the books that the NPC team members, Gabriel Garcia Marquez and Isabel Allende, are most proud of. Gabriel highlighted 'Cien años de soledad,' while Isabel spoke of 'La Casa de los Espíritus.' Both authors expressed deep personal connections to their works, illustrating their significance in Latin American literature and their own identities.", 'recommendations': 'Encourage further engagement with each author to explore more about their literary contributions, or consider asking about themes in their works or their thoughts on current literary trends.'}, 'execution_history': [{'messages': ...}]}
 ```
 
+LLM responses can be obtained without NPCs as well.
+
+```
+from npcpy.llm_funcs import get_llm_response
+response = get_llm_response("Who was the celtic Messenger god?", model='llama3.2', provider='ollama')
+print(response['response'])
+```
+
+```
+The Celtic messenger god is often associated with the figure of Tylwyth Teg, also known as the Tuatha Dé Danann (meaning "the people of the goddess Danu"). However, among the various Celtic cultures, there are a few gods and goddesses that served similar roles.
+
+One of the most well-known Celtic messengers is Brigid's servant, Líth (also spelled Lid or Lith), who was believed to be a spirit guide for messengers and travelers in Irish mythology.
+```
+The structure of npcpy also allows one to pass an npc
+to `get_llm_response` in addition to using the NPC's wrapped method, 
+allowing you to be flexible in your implementation and testing.
+```
+from npcpy.npc_compiler import NPC
+from npcpy.llm_funcs import get_llm_response
+simon = NPC(
+          name='Simon Bolivar',
+          primary_directive='Liberate South America from the Spanish Royalists.',
+          model='qwen3',
+          provider='ollama'
+          )
+response = get_llm_response("Who was the mythological chilean bird that guides lucky visitors to gold?", npc=simon)
+print(response['response'])
+```
+
+
+
+`npcpy` also supports streaming responses, with the `response` key containing a generator in such cases which can be printed and processed through the print_and
+
+
+```
+from npcpy.npc_sysenv import print_and_process_stream
+from npcpy.llm_funcs import get_llm_response
+response = get_llm_response("When did the united states government begin sendinng advisors to vietnam?", model='llama3.2', provider='ollama', stream = True)
+
+full_response = print_and_process_stream(response['response'], 'llama3.2', 'ollama')
+```
+Return structured outputs by specifying `format='json'` or passing a Pydantic schema. When specific formats are extracted, `npcpy`'s `get_llm_response` will convert the response from its string representation so you don't have to worry about that. 
+
+```
+from npcpy.llm_funcs import get_llm_response
+response = get_llm_response("What is the sentiment of the american people towards the repeal of Roe v Wade? Return a json object with `sentiment` as the key and a float value from -1 to 1 as the value", model='gemma3:1b', provider='ollama', format='json')
+
+print(response['response'])
+```
+```
+{'sentiment': -0.7}
+```
+
+The `get_llm_response` function also can take a list of messages and will additionally return the messages with the user prompt and the assistant response appended if the response is not streamed. If it is streamed, the user must manually append the conversation result as part of their workflow if they want to then pass the messages back in.
+
+Additionally, one can pass attachments. Here we demonstrate both
+```
+from npcpy.llm_funcs import get_llm_response
+messages = [{'role': 'system', 'content': 'You are an annoyed assistant.'}]
+
+response = get_llm_response("What is the meaning of caesar salad", model='gpt-4o-mini', provider='openai', images=['./Language_Evolution_and_Innovation_experiment.png'], messages=messages)
+
+
+
+```
+Easily create images with the generate_image function, using models available through Huggingface's diffusers library or from OpenAI or Gemini.
+```
+from npcpy.llm_funcs import gen_image
+image = gen_image("make a picture of the moon in the summer of marco polo", model='runwayml/stable-diffusion-v1-5', provider='diffusers')
+
+
+image = gen_image("make a picture of the moon in the summer of marco polo", model='dall-e-2', provider='openai')
+
+
+# edit images with 'gpt-image-1' or gemini's multimodal models, passing image paths, byte code images, or PIL instances.
+
+image = gen_image("make a picture of the moon in the summer of marco polo", model='gpt-image-1', provider='openai', attachments=['/path/to/your/image.jpg', your_byte_code_image_here, your_PIL_image_here])
+
+
+image = gen_image("edit this picture of the moon in the summer of marco polo so that it looks like it is in the winter of nishitani", model='gemini-2.0-flash', provider='gemini', attachments= [])
+
+```
+
+Likewise, generate videos :
+
+```
+from npcpy.llm_funcs import gen_video
+image = gen_video("make a video of the moon in the summer of marco polo", model='runwayml/stable-diffusion-v1-5', provider='diffusers')
+```
+
 
-See more examples of how to use `npcpy` to create agents and agentic systems [here](https://github.com/cagostino/npcpy/blob/main/docs/npcpy.md). `npcpy` can include images, pdfs, and csvs in its llm response generation. 
+For more examples of how to use `npcpy` to simplify your LLM workflows  or to create agents or multi-agent systems, see [here](https://github.com/cagostino/npcpy/blob/main/docs/npcpy.md). `npcpy` can include images, pdfs, and csvs in its llm response generation. 
 
 
 ## Inference Capabilities
@@ -322,19 +411,37 @@ The following are the current programs in the NPC shell:
   <img src="https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy/npc_team/alicanto.png" alt="logo for deep research", width=250></a>
 </p>
 
-  - start a sequence:
+  - Examples:
     ```
     npc alicanto "What are the implications of quantum computing for cybersecurity?"
     ```
+
+    - With more researchers and deeper exploration
+    
+    ```
+    npc alicanto "How might climate change impact global food security?" --num-npcs 8 --depth 5
+
+    ```
+    - Control exploration vs. exploitation balance
+
+    ```
+    npc alicanto "What ethical considerations should guide AI development?" --exploration 0.5
+
+    ```
+    - Different output formats
+    ```    
+    npc alicanto "What is the future of remote work?" --format report
+    ```
  
 ## `pti`
 -  a reasoning REPL loop with explicit checks to request inputs from users following thinking traces.
  
 <p align="center"><a href ="https://github.com/cagostino/npcpy/blob/main/docs/pti.md"> 
   <img src="https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy/npc_team/frederic4.png" alt="npcpy logo of frederic the bear and the pti logo", width=250></a>
 </p>
-Speak frederic the bear who, once he's done thinking, asks you for input before trudging on so it can work with confidence.
-```
+Speak with frederic the bear who, once he's done thinking, asks you for input before trudging on so it can work with confidence.
+
+```bash
 pti
 ```
 
@@ -353,7 +460,8 @@ pti
   <img src="https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy/npc_team/yap.png" alt="logo for yap ", width=250></a>
 </p>
 
-- an agentic voice control loop with a specified agent. 
+- an agentic voice control loop with a specified agent. When launching `yap`, the user enters the typical `npcsh` agentic loop except that the system is waiting for either text or audio input.
+
 ```
 yap 
 ```
@@ -379,6 +487,7 @@ yap
     npc wander "How can I improve my creative writing?" --num-events 5
     ```
 
+
 ## Enabling Innovation
 - `npcpy` is a framework that speeds up and simplifies the development of NLP-based or Agent-based applications and provides developers and researchers with methods to explore and test across dozens of models, providers, and personas as well as other model-level hyperparameters (e.g. `temperature`, `top_k`, etc.), incorporating an array of data sources and common tools.
 - The `npcpy` agent data layer makes it easy to set up teams and serve them so you can focus more on the agent personas and less on the nitty gritty of inference.
@@ -420,14 +529,13 @@ ollama pull llava:7b
 ollama pull nomic-embed-text
 pip install npcpy
 # if you want to install with the API libraries
-pip install npcpy[lite]
+pip install 'npcpy[lite]'
 # if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
-pip install npcpy[local]
+pip install 'npcpy[local]'
 # if you want to use tts/stt
-pip install npcpy[yap]
-
+pip install 'npcpy[yap]'
 # if you want everything:
-pip install npcpy[all]
+pip install 'npcpy[all]'
 ```
 </details>
 
@@ -473,9 +581,9 @@ Then, in a powershell. Download and install ffmpeg.
 ollama pull llama3.2
 ollama pull llava:7b
 ollama pull nomic-embed-text
-pip install npcsh
+pip install npcpy
 # if you want to install with the API libraries
-pip install npcsh[lite]
+pip install npcpy[lite]
 # if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
 pip install npcpy[local]
 # if you want to use tts/stt
@@ -484,7 +592,7 @@ pip install npcpy[yap]
 # if you want everything:
 pip install npcpy[all]
 ```
-As of now, npcsh appears to work well with some of the core functionalities like /ots and /whisper.
+As of now, npcsh appears to work well with some of the core functionalities like /ots and /yap.
 
 </details>
 

docs/alicanto.md

@@ -0,0 +1,58 @@
+# Alicanto: Deep Thematic Research
+
+Alicanto is a deep research method inspired by the Chilean mythological bird that can lead miners to gold or to death. In NPC Shell, Alicanto conducts extensive multi-perspective research on any topic by exploring with both breadth (across different expert perspectives) and depth (diving deeper into promising directions).
+
+## Overview
+
+Alicanto creates a team of diverse AI researchers who explore your research question from multiple angles. It then analyzes their findings, identifies thematic clusters, evaluates the quality and risk of each insight, and produces a comprehensive report with "gold insights" (high quality, low risk) and "cliff warnings" (high risk).
+
+## Usage
+
+```bash
+# Basic usage
+npc alicanto "What are the implications of quantum computing for cybersecurity?"
+
+# With more researchers and deeper exploration
+npc alicanto "How might climate change impact global food security?" --num-npcs 8 --depth 5
+
+# Control exploration vs. exploitation balance
+npc alicanto "What ethical considerations should guide AI development?" --exploration 0.5
+
+# Different output formats
+npc alicanto "What is the future of remote work?" --format report
+```
+
+## Options
+
+- `--num-npcs N`: Number of researcher NPCs to use (default: 5)
+- `--depth N`: Depth of research chains for each NPC (default: 3)
+- `--exploration FLOAT`: Balance between exploration and exploitation (0.0-1.0, default: 0.3)
+- `--format FORMAT`: Output format: "report" (default), "summary", or "full"
+
+## How it Works
+
+1. **Expert Generation**: Creates a diverse team of AI researchers with different expertise and perspectives
+2. **Research Chains**: Each researcher conducts a series of research steps, going deeper with each iteration
+3. **Insight Extraction**: Key insights are extracted from each research chain
+4. **Thematic Grouping**: Insights are grouped into thematic clusters across researchers
+5. **Quality Evaluation**: Each theme is evaluated for quality (novelty, depth, practicality, evidence) and risk
+6. **Gold and Cliff Identification**: High-quality insights with low risk are marked as "gold insights," while high-risk insights are flagged as "cliff warnings"
+7. **Integration**: A comprehensive research report synthesizes findings and provides guidance
+
+## Example Output
+
+The output includes:
+- An integrated overview connecting all themes
+- The most significant overall findings
+- Specific recommendations for further research
+- Particular cautions and limitations
+- Clearly marked gold insights and cliff warnings
+- Detailed thematic findings with quality and risk scores
+
+## Use Cases
+
+- Exploring complex, multifaceted topics
+- Getting diverse perspectives on controversial issues
+- Identifying promising research directions
+- Evaluating the quality and risk of different approaches
+- Discovering connections between seemingly unrelated ideas

docs/index.md

@@ -1,13 +1,10 @@
-
-
-
 <p align="center">
   <a href= "https://github.com/cagostino/npcpy/blob/main/docs/npcpy.md"> 
   <img src="https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy/npc-python.png" alt="npc-python logo" width=250></a>
 </p>
 
 
-Interested to stay in the loop and to hear the latest and greatest about `npcpy` ? Be sure to sign up for the [npcsh newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A)!
+Interested to stay in the loop and to hear the latest and greatest about `npcpy` ? Be sure to sign up for the [npcpy newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A)!
 
 Welcome to `npcpy`, the python library for the NPC Toolkit and the home of the core command-line programs that make up the NPC Shell (`npcsh`). 
 
@@ -119,7 +116,7 @@ handling agent pass
 - [NPC Shell](npcsh.md)
 - [NPC CLI ](api/npc_cli.md)
 
-- [Alicanto](akicanto.md)
+- [Alicanto](alicanto.md)
 - [Guac](guac.md)
 - [PTI](pti.md)
 - [Spool](spool.md)
@@ -139,12 +136,12 @@ handling agent pass
 Contributions are welcome! Please submit issues and pull requests on the GitHub repository.
 
 ## Support
-If you appreciate the work here, [consider supporting NPC Worldwide](https://buymeacoffee.com/npcworldwide). If you'd like to explore how to use `npcsh` to help your business, please reach out to info@npcworldwi.de .
+If you appreciate the work here, [consider supporting NPC Worldwide](https://buymeacoffee.com/npcworldwide). If you'd like to explore how to use `npcpy` to help your business, please reach out to info@npcworldwi.de .
 
 
 ## NPC Studio
 Coming soon! NPC Studio will be a desktop application for managing chats and agents on your own machine.
-Be sure to sign up for the [npcsh newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A) to hear updates!
+Be sure to sign up for the [npcpy newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A) to hear updates!
 
 ## License
 This project is licensed under the MIT License.