igris-soul 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,8 @@
 # Igris Soul
 
-> To use Igris Soul from anywhere, install it globally and run `Arise`:
+> Your personal AI assistant in the terminal, inspired by Igris from Solo Leveling.
+>
+> Install it globally and summon Igris from anywhere:
 >
 > ```bash
 > npm install -g igris-soul
@@ -9,33 +11,231 @@
 
 ## Disclaimer
 
-This project sends your prompts to Google Gemini and may send web-search requests to Tavily. Do not enter passwords, private keys, personal data, confidential business information, or any other sensitive information into the assistant. You are responsible for reviewing generated answers and for the API usage and charges associated with your keys. This project is provided for educational and personal use without guarantees about accuracy, availability, or fitness for a particular purpose.
+This project sends your prompts to Google Gemini and may send web-search requests to Tavily. Do not enter passwords, private keys, personal data, confidential business information, or any other sensitive information into the assistant.
+
+You are responsible for reviewing generated answers and for the API usage and charges associated with your API keys.
+
+This project is provided for educational and personal use without guarantees about accuracy, availability, or fitness for a particular purpose.
+
+---
 
 ## Requirements
 
-- Node.js 20 or newer
-- A Google Gemini API key
-- A Tavily API key for current-information searches
+Before installing Igris Soul, make sure you have:
+
+* Node.js 20 or newer
+* A Google Gemini API key
+* A Tavily API key for current-information searches
+* An npm account if you want to install or publish the package through npm
+
+---
+
+# Installation
+
+## Install Globally
+
+To use Igris Soul from anywhere on your computer:
+
+```bash
+npm install -g igris-soul
+```
+
+After installation, start Igris with:
+
+```bash
+Arise
+```
+
+You can run `Arise` from any directory.
+
+For example:
+
+```bash
+C:\Users\YourName> Arise
+```
+
+or:
+
+```bash
+D:\Projects\MyProject> Arise
+```
+
+or:
+
+```bash
+E:\Anything> Arise
+```
+
+Igris does not depend on the directory from which you launch it.
+
+---
+
+# First-Time Setup
+
+On the first launch, Igris automatically creates its configuration directory in your home directory:
+
+```text
+~/.igris/
+```
+
+It will automatically create:
+
+```text
+~/.igris/
+├── .env
+└── user.json
+```
+
+You do **not** need to manually create these files.
+
+Igris will ask for the required API keys if they are not already configured:
+
+```text
+Enter your Gemini API key:
+Enter your Tavily API key:
+```
+
+The keys are then stored locally in:
 
-## Configuration
+```text
+~/.igris/.env
+```
+
+On Windows, this is typically:
+
+```text
+C:\Users\YourName\.igris\.env
+```
+
+Your name is stored separately in:
+
+```text
+C:\Users\YourName\.igris\user.json
+```
+
+On future launches, Igris automatically loads the saved configuration.
+
+---
 
-For a local checkout, create a `.env` file in the project root. For a global installation, create `.igris/.env` in your home directory. Use `.env.example` as the template:
+# Configuration
+
+The automatically created `.env` file contains:
 
 ```env
 GENAI_API_KEY=your_google_gemini_api_key
 TAVILY_API_KEY=your_tavily_api_key
 ```
 
-Never commit `.env` or share its contents. It is already excluded by `.gitignore`.
+### Environment Variables
+
+| Variable         | Purpose                         |
+| ---------------- | ------------------------------- |
+| `GENAI_API_KEY`  | Google Gemini API key           |
+| `TAVILY_API_KEY` | Tavily API key for web searches |
+
+You can manually edit:
+
+```text
+~/.igris/.env
+```
+
+if you need to change your API keys.
+
+### Security
+
+Never commit or share your `.env` file.
+
+Never put real API keys inside the source code.
+
+The `.env` file contains sensitive credentials and should remain on your local machine.
+
+The project includes `.env.example` as a safe template:
+
+```env
+GENAI_API_KEY=
+TAVILY_API_KEY=
+```
+
+---
+
+# Running Igris
+
+After installation:
+
+```bash
+Arise
+```
+
+You will see:
+
+```text
++----------------------+
+|        IGRIS         |
+|      AGENT ONLINE    |
++----------------------+
+
+Hi, My Lord, I am Igris, your loyal servant.
+How may I assist you today?
+```
+
+You can then enter your prompts directly in the terminal.
+
+Example:
+
+```text
+You: Explain binary search in Java
+
+Igris:
+...
+```
+
+To exit the assistant:
+
+```text
+exit
+```
+
+or:
+
+```text
+quit
+```
+
+---
+
+# Features
+
+* Interactive terminal-based AI assistant
+* Google Gemini-powered responses
+* Streaming AI responses
+* Tavily web search for current information
+* Conversation history during the current session
+* Personalized responses using your saved name
+* First-launch name setup
+* Persistent configuration
+* Automatic `.igris` directory creation
+* Automatic `.env` creation
+* Global CLI access
+* Runs from any directory
+* `Arise` command for launching the assistant
 
-When both files exist, the `.env` file in the current directory takes priority over the home-directory configuration.
+---
 
-## Run From This Repository
+# Local Development
 
-Install dependencies and start Igris Soul:
+If you want to run Igris Soul directly from the source code instead of installing it globally:
+
+Clone or download the repository and enter the project directory.
+
+Install dependencies:
 
 ```bash
 npm install
+```
+
+Then start Igris:
+
+```bash
 npm start
 ```
 
@@ -45,50 +245,164 @@ You can also run:
 node index.js
 ```
 
-Type `exit` or `quit` to close the assistant.
+The same `~/.igris/.env` configuration is used.
+
+---
+
+# Test the Package Locally
+
+Before publishing a new version to npm, you can test the CLI directly from the package directory.
 
-## Install As A Global CLI
+Install the local package globally:
 
 ```bash
-npm install -g igris-soul
-Arise
+npm install -g .
 ```
 
-The `arise`, `igris-soul`, and `igris` aliases are also available. To test the package locally before publishing:
+Then run:
 
 ```bash
-npm install -g .
 Arise
 ```
 
-## Features
+This allows you to test the global CLI behavior using your local source code.
+
+---
+
+# Updating Igris Soul
 
-- Interactive terminal conversation with streamed responses
-- Google Gemini-powered answers
-- Tavily web search for current information
-- Conversation history during the current session
-- First-launch name setup
-- Persistent name storage in `~/.igris/user.json`
-- `Arise`, `igris-soul`, and `igris` global commands
+When a new version is published, update your global installation with:
 
-The saved name belongs to the local operating-system user account and remains available across directories and package updates until the file is deleted.
+```bash
+npm install -g igris-soul@latest
+```
+
+Your personal configuration remains outside the npm package:
+
+```text
+~/.igris/
+├── .env
+└── user.json
+```
 
-## Publishing
+Therefore, updating the package does not require you to enter your API keys again.
 
-Log in to npm and publish the package:
+---
+
+# Uninstalling
+
+To remove the globally installed package:
+
+```bash
+npm uninstall -g igris-soul
+```
+
+Your personal Igris configuration remains in:
+
+```text
+~/.igris/
+```
+
+If you want to completely remove your local Igris configuration as well, delete the `.igris` directory manually.
+
+---
+
+# Publishing to npm
+
+If you are the package maintainer and want to publish a new version:
+
+First, log in to npm:
 
 ```bash
 npm login
+```
+
+Verify your account:
+
+```bash
+npm whoami
+```
+
+Run the tests:
+
+```bash
 npm test
-npm publish
 ```
 
-To verify the package without uploading it:
+Check what will be included in the package:
 
 ```bash
 npm publish --dry-run
 ```
 
-## License
+If everything looks correct, publish:
+
+```bash
+npm publish
+```
+
+## Updating the Version
+
+npm does not allow publishing the same package version twice.
+
+For a bug fix:
+
+```bash
+npm version patch
+```
+
+For a new feature:
+
+```bash
+npm version minor
+```
+
+For a breaking change:
+
+```bash
+npm version major
+```
+
+Then publish the new version:
+
+```bash
+npm publish
+```
+
+Example:
+
+```text
+1.0.0 → 1.0.1
+```
+
+---
+
+# Package Usage
+
+Igris Soul is primarily designed as a global terminal assistant.
+
+Install:
+
+```bash
+npm install -g igris-soul
+```
+
+Run:
+
+```bash
+Arise
+```
+
+The package is installed globally, while user-specific configuration is stored separately in:
+
+```text
+~/.igris/
+```
+
+This allows Igris to maintain its configuration independently of the directory from which it is launched.
+
+---
+
+# License
 
 ISC

package/index.js

@@ -1,9 +1,12 @@
-#!/usr/bin/env node
-
 import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
 import { config } from "dotenv";
 import { tavily } from "@tavily/core";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import {
+  mkdir,
+  readFile,
+  writeFile,
+  access,
+} from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import rl from "readline/promises";
@@ -17,15 +20,128 @@ import {
 } from "langchain";
 import * as z from "zod";
 
+/* =========================================================
+   IGRIS CONFIGURATION
+   ========================================================= */
+
+const igrisDir = join(homedir(), ".igris");
+const envPath = join(igrisDir, ".env");
+const userDataPath = join(igrisDir, "user.json");
+
+// Create ~/.igris automatically
+await mkdir(igrisDir, { recursive: true });
+
+// Check whether .env exists
+async function ensureEnvFile() {
+  try {
+    await access(envPath);
+  } catch {
+    await writeFile(
+      envPath,
+      `GENAI_API_KEY=\nTAVILY_API_KEY=\n`,
+      "utf8",
+    );
+
+    console.log(`
+Igris configuration created.
+
+Configuration file:
+${envPath}
+
+You will now be asked for your API keys.
+`);
+  }
+}
+
+await ensureEnvFile();
+
+// Load environment variables from ~/.igris/.env
 config({
-  path: [join(process.cwd(), ".env"), join(homedir(), ".igris", ".env")],
+  path: envPath,
   quiet: true,
 });
+
+/* =========================================================
+   READ / SAVE API KEYS
+   ========================================================= */
+
+async function getApiKey(variableName, displayName) {
+  let value = process.env[variableName]?.trim();
+
+  if (value) {
+    return value;
+  }
+
+  const key = await readline.question(
+    `${displayName}: `,
+  );
+
+  value = key.trim();
+
+  if (!value) {
+    console.error(`\n${displayName} cannot be empty.`);
+    process.exit(1);
+  }
+
+  // Read existing .env
+  let envContent = "";
+
+  try {
+    envContent = await readFile(envPath, "utf8");
+  } catch {
+    envContent = "";
+  }
+
+  const regex = new RegExp(`^${variableName}=.*$`, "m");
+
+  if (regex.test(envContent)) {
+    envContent = envContent.replace(
+      regex,
+      `${variableName}=${value}`,
+    );
+  } else {
+    envContent += `\n${variableName}=${value}\n`;
+  }
+
+  await writeFile(envPath, envContent.trim() + "\n", "utf8");
+
+  process.env[variableName] = value;
+
+  return value;
+}
+
+/* =========================================================
+   READLINE
+   ========================================================= */
+
+const readline = rl.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+/* =========================================================
+   API CONFIGURATION
+   ========================================================= */
+
+const genaiApiKey = await getApiKey(
+  "GENAI_API_KEY",
+  "Enter your Gemini API key",
+);
+
+const tavilyApiKey = await getApiKey(
+  "TAVILY_API_KEY",
+  "Enter your Tavily API key",
+);
+
+/* =========================================================
+   TAVILY
+   ========================================================= */
+
 const tavly = tavily({
-  apiKey: process.env.TAVILY_API_KEY,
+  apiKey: tavilyApiKey,
 });
+
 async function getLetestInfos({ query }) {
-  // return "India's latest updates as per today are : New kolkata metro staion inaugurated, New AI policy released by the government, and the stock market is showing positive trends.";
   const response = await tavly.search(query, {
     searchDepth: "fast",
     maxResults: 3,
@@ -33,8 +149,11 @@ async function getLetestInfos({ query }) {
   });
 
   const results = response.results;
-  const content = results.map((result) => result.content).join("\n\n");
-  // console.log("Content:", content);
+
+  const content = results
+    .map((result) => result.content)
+    .join("\n\n");
+
   return content;
 }
 
@@ -51,76 +170,115 @@ const getLatestInfosTool = tool(getLetestInfos, {
   }),
 });
 
-const readline = rl.createInterface({
-  input: process.stdin,
-  output: process.stdout,
-});
-
-const userDataPath = join(homedir(), ".igris", "user.json");
+/* =========================================================
+   USER DATA
+   ========================================================= */
 
 async function getUserName() {
   try {
-    const userData = JSON.parse(await readFile(userDataPath, "utf8"));
+    const userData = JSON.parse(
+      await readFile(userDataPath, "utf8"),
+    );
+
     return userData.name;
   } catch {
     const name = (
-      await readline.question("What is your name, My Lord? ")
+      await readline.question(
+        "What is your name, My Lord? ",
+      )
     ).trim();
-    await mkdir(join(homedir(), ".igris"), { recursive: true });
-    await writeFile(userDataPath, JSON.stringify({ name }, null, 2));
+
+    await writeFile(
+      userDataPath,
+      JSON.stringify({ name }, null, 2),
+      "utf8",
+    );
+
     return name;
   }
 }
 
 const userName = await getUserName();
 
+/* =========================================================
+   GEMINI MODEL
+   ========================================================= */
+
 const model = new ChatGoogleGenerativeAI({
   model: "gemini-3.5-flash-lite",
-  apiKey: process.env.GENAI_API_KEY,
+  apiKey: genaiApiKey,
 });
 
+/* =========================================================
+   AGENT
+   ========================================================= */
+
 const agent = createAgent({
   model,
   tools: [getLatestInfosTool],
 });
 
-// const response = await model.stream("Write a code in Java that actually shows abstraction, encapsulation, inheritance and polymorphism in a single program.go");
-// for await (const chunk of response) {
-//   process.stdout.write(chunk.text);
-// }
-
-// const prompt = await readline.question("Enter your prompt: ");
-// console.log("Prompt:", prompt);
-// readline.close();
+/* =========================================================
+   SYSTEM MESSAGE
+   ========================================================= */
 
 const messages = [
   new SystemMessage(`
-    You are Igris from Solo leveling, and the user's name is ${userName}. Always address the user as My Lord. You are a Senior Software Developer and also an ML engineer, and your task is to answer queries as per the solo levelling style. Dont give unnecessary long responses, give responses to the point, and use plain text without markdown.
-    Today is ${new Date().toLocaleDateString()} and the time is ${new Date().toLocaleTimeString()}.
-    Dont use always te date and time, but for styling or poetic respsonse you can use it, but dont use it in every response, use it only when needed.
-    `),
+You are Igris from Solo Leveling, and the user's name is ${userName}.
+
+Always address the user as My Lord.
+
+You are a Senior Software Developer and ML Engineer.
+
+Your task is to answer queries in the Solo Leveling style.
+
+Do not give unnecessarily long responses.
+Give responses to the point.
+Use plain text without markdown.
+
+Today is ${new Date().toLocaleDateString()} and the time is ${new Date().toLocaleTimeString()}.
+
+Do not always mention the date and time.
+Use them only when needed for styling, context, or a poetic response.
+`),
 ];
 
+/* =========================================================
+   START IGRIS
+   ========================================================= */
+
 console.log(`
 +----------------------+
 |        IGRIS         |
 |      AGENT ONLINE    |
 +----------------------+
 
-Hi, My Lord, I am Igris, your loyal servant. How may I assist you today?\n
+Hi, My Lord, I am Igris, your loyal servant.
+How may I assist you today?
 `);
 
-// console.log(
-//   "Hi, My Lord, I am Igris, your loyal servant. How may I assist you today?\n",
-// );
+/* =========================================================
+   CHAT LOOP
+   ========================================================= */
+
 try {
   while (true) {
     const prompt = await readline.question("You: ");
-    if (["exit", "quit"].includes(prompt.trim().toLowerCase())) {
+
+    if (
+      ["exit", "quit"].includes(
+        prompt.trim().toLowerCase(),
+      )
+    ) {
       break;
     }
 
+    if (!prompt.trim()) {
+      continue;
+    }
+
     messages.push(new HumanMessage(prompt));
+
     const stream = await agent.stream(
       {
         messages,
@@ -129,17 +287,23 @@ try {
         streamMode: "messages",
       },
     );
+
     let aiResponse = "";
+
     console.log("Igris: ");
+
     for await (const [chunk] of stream) {
       if (chunk instanceof AIMessageChunk) {
         process.stdout.write(chunk.text);
         aiResponse += chunk.text;
       }
     }
+
     messages.push(new AIMessage(aiResponse));
+
     process.stdout.write("\n\n");
   }
 } finally {
   readline.close();
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igris-soul",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A terminal AI assistant powered by Gemini and Tavily.",
   "license": "ISC",
   "author": "Barshan Majumdar",