node-behind-api-client 2.0.48

package/docs/behind-api-client/rag/storage/README.md

@@ -0,0 +1,519 @@
+# RAG Storage API Extension
+
+This document extends the main EasyJob JavaScript API Client Documentation with detailed information about the RAG (Retrieval-Augmented Generation) Storage API methods.
+
+## Overview
+
+The RAG Storage API provides vector-based semantic search and document storage capabilities. It allows you to store text documents with metadata and perform intelligent semantic searches across stored content. This is particularly useful for building knowledge bases, document retrieval systems, and AI-powered search functionality.
+
+---
+
+## RAG Storage API
+
+### behindAPI.rag.V10.storage.search(query, limit)
+Performs a semantic search across stored documents using vector embeddings to find the most relevant content.
+
+**Parameters:**
+- `query` (string, required) - The search query text to find semantically similar documents
+- `limit` (integer, required) - Maximum number of results to return
+
+**Usage:**
+```javascript
+const result = await behindAPI.rag.V10.storage.search(
+    "software development best practices",
+    5
+);
+
+// Response:
+{
+    success: true,
+    data: [
+        {
+            text: "Software development best practices include code reviews...",
+            doc_type: "article",
+            source: "internal_wiki",
+            book_id: "dev-handbook",
+            chapter_id: "chapter-3",
+            page_id: "page-12",
+            similarity_score: 0.92
+        },
+        {
+            text: "Effective software development requires proper testing...",
+            doc_type: "guide",
+            source: "training_materials",
+            book_id: "quality-assurance",
+            chapter_id: "chapter-1",
+            page_id: "page-5",
+            similarity_score: 0.87
+        }
+        // ... additional results
+    ]
+}
+```
+
+### behindAPI.rag.V10.storage.put(text, docType, source, bookId, chapterId, pageId)
+Stores a text document with metadata in the RAG storage system, automatically generating vector embeddings for semantic search.
+
+**Parameters:**
+- `text` (string, required) - The text content to store
+- `docType` (string, required) - The type/category of the document (e.g., "article", "guide", "manual", "faq")
+- `source` (string, required) - The source or origin of the document (e.g., "internal_wiki", "external_api", "user_upload")
+- `bookId` (string, required) - Identifier for the book/collection this document belongs to
+- `chapterId` (string, required) - Identifier for the chapter/section within the book
+- `pageId` (string, required) - Identifier for the specific page/document
+
+**Usage:**
+```javascript
+const result = await behindAPI.rag.V10.storage.put(
+    "JavaScript is a versatile programming language used for web development. It supports both functional and object-oriented programming paradigms.",
+    "article",
+    "internal_wiki",
+    "programming-guide",
+    "chapter-javascript",
+    "page-intro"
+);
+
+// Response:
+{
+    success: true,
+    data: {
+        document_id: "550e8400-e29b-41d4-a716-446655440000",
+        message: "Document stored successfully"
+    }
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Search Result Object
+Each search result contains:
+
+- `text` (string) - The stored text content
+- `doc_type` (string) - Type of document
+- `source` (string) - Source of the document
+- `book_id` (string) - Book/collection identifier
+- `chapter_id` (string) - Chapter/section identifier
+- `page_id` (string) - Page/document identifier
+- `similarity_score` (float) - Semantic similarity score (0-1, where 1 is most similar)
+
+### Storage Response Object
+When storing a document:
+
+- `document_id` (UUID) - Unique identifier for the stored document
+- `message` (string) - Status message confirming storage
+
+---
+
+## Complete Usage Examples
+
+### Example 1: Building a Knowledge Base
+
+```javascript
+// Store company documentation in the RAG system
+async function buildKnowledgeBase() {
+    const documents = [
+        {
+            text: "Our company vacation policy allows 20 days of paid time off per year. Employees must request vacation at least 2 weeks in advance.",
+            docType: "policy",
+            source: "hr_handbook",
+            bookId: "employee-handbook",
+            chapterId: "benefits",
+            pageId: "vacation-policy"
+        },
+        {
+            text: "The onboarding process for new employees takes approximately 2 weeks. It includes orientation, system setup, and initial training sessions.",
+            docType: "procedure",
+            source: "hr_handbook",
+            bookId: "employee-handbook",
+            chapterId: "onboarding",
+            pageId: "overview"
+        },
+        {
+            text: "All code changes must go through a peer review process before merging to the main branch. At least one approval is required.",
+            docType: "policy",
+            source: "engineering_wiki",
+            bookId: "dev-standards",
+            chapterId: "code-review",
+            pageId: "process"
+        }
+    ];
+
+    try {
+        console.log("Building knowledge base...");
+        
+        for (const doc of documents) {
+            const result = await behindAPI.rag.V10.storage.put(
+                doc.text,
+                doc.docType,
+                doc.source,
+                doc.bookId,
+                doc.chapterId,
+                doc.pageId
+            );
+
+            if (result.success) {
+                console.log(`✓ Stored: ${doc.pageId}`);
+            } else {
+                console.error(`✗ Failed to store: ${doc.pageId}`);
+            }
+        }
+
+        console.log("\nKnowledge base built successfully!");
+        return true;
+
+    } catch (error) {
+        console.error("Error building knowledge base:", error);
+        return false;
+    }
+}
+```
+
+### Example 2: Semantic Search with Context
+
+```javascript
+// Search for relevant information and provide context
+async function findRelevantInformation(userQuery) {
+    try {
+        console.log(`Searching for: "${userQuery}"\n`);
+
+        // Perform semantic search
+        const searchResult = await behindAPI.rag.V10.storage.search(userQuery, 3);
+
+        if (!searchResult.success) {
+            console.error("Search failed");
+            return null;
+        }
+
+        // Process and display results
+        console.log(`Found ${searchResult.data.length} relevant results:\n`);
+
+        searchResult.data.forEach((result, index) => {
+            console.log(`Result ${index + 1}:`);
+            console.log(`  Similarity: ${(result.similarity_score * 100).toFixed(1)}%`);
+            console.log(`  Type: ${result.doc_type}`);
+            console.log(`  Source: ${result.source}`);
+            console.log(`  Location: ${result.book_id} > ${result.chapter_id} > ${result.page_id}`);
+            console.log(`  Content: ${result.text.substring(0, 100)}...`);
+            console.log();
+        });
+
+        return searchResult.data;
+
+    } catch (error) {
+        console.error("Error during search:", error);
+        return null;
+    }
+}
+
+// Example usage
+findRelevantInformation("How do I request time off?");
+findRelevantInformation("What is the code review process?");
+```
+
+### Example 3: Document Categorization and Storage
+
+```javascript
+// Organize and store documents by category
+async function organizeDocuments(category, documents) {
+    const results = {
+        success: 0,
+        failed: 0,
+        details: []
+    };
+
+    try {
+        for (const doc of documents) {
+            const result = await behindAPI.rag.V10.storage.put(
+                doc.content,
+                category,
+                doc.source || "default",
+                doc.bookId || `${category}-collection`,
+                doc.chapterId || "general",
+                doc.pageId || `page-${Date.now()}`
+            );
+
+            if (result.success) {
+                results.success++;
+                results.details.push({
+                    pageId: doc.pageId,
+                    status: "stored",
+                    documentId: result.data.document_id
+                });
+            } else {
+                results.failed++;
+                results.details.push({
+                    pageId: doc.pageId,
+                    status: "failed",
+                    error: result.message
+                });
+            }
+        }
+
+        console.log(`\nCategorization Results for "${category}":`);
+        console.log(`  Successfully stored: ${results.success}`);
+        console.log(`  Failed: ${results.failed}`);
+
+        return results;
+
+    } catch (error) {
+        console.error("Error organizing documents:", error);
+        return results;
+    }
+}
+
+// Example: Store FAQ documents
+const faqDocuments = [
+    {
+        content: "To reset your password, click on 'Forgot Password' on the login page and follow the instructions sent to your email.",
+        source: "support_center",
+        bookId: "faqs",
+        chapterId: "account",
+        pageId: "password-reset"
+    },
+    {
+        content: "You can update your profile information by navigating to Settings > Profile and clicking the Edit button.",
+        source: "support_center",
+        bookId: "faqs",
+        chapterId: "account",
+        pageId: "profile-update"
+    }
+];
+
+organizeDocuments("faq", faqDocuments);
+```
+
+### Example 4: Advanced Search and Filtering
+
+```javascript
+// Perform search with result filtering and ranking
+async function advancedSearch(query, options = {}) {
+    const {
+        minSimilarity = 0.7,
+        maxResults = 10,
+        filterByType = null,
+        filterBySource = null
+    } = options;
+
+    try {
+        // Perform initial search with higher limit
+        const searchResult = await behindAPI.rag.V10.storage.search(query, maxResults * 2);
+
+        if (!searchResult.success) {
+            return { success: false, message: "Search failed" };
+        }
+
+        // Filter and process results
+        let filteredResults = searchResult.data.filter(result => {
+            // Filter by minimum similarity
+            if (result.similarity_score < minSimilarity) return false;
+
+            // Filter by document type if specified
+            if (filterByType && result.doc_type !== filterByType) return false;
+
+            // Filter by source if specified
+            if (filterBySource && result.source !== filterBySource) return false;
+
+            return true;
+        });
+
+        // Limit to maxResults
+        filteredResults = filteredResults.slice(0, maxResults);
+
+        // Group by source
+        const groupedBySource = filteredResults.reduce((acc, result) => {
+            if (!acc[result.source]) {
+                acc[result.source] = [];
+            }
+            acc[result.source].push(result);
+            return acc;
+        }, {});
+
+        console.log(`\nAdvanced Search Results for: "${query}"`);
+        console.log(`Total matches: ${filteredResults.length}\n`);
+
+        Object.entries(groupedBySource).forEach(([source, results]) => {
+            console.log(`Source: ${source} (${results.length} results)`);
+            results.forEach((result, idx) => {
+                console.log(`  ${idx + 1}. [${result.doc_type}] ${result.book_id}/${result.page_id}`);
+                console.log(`     Similarity: ${(result.similarity_score * 100).toFixed(1)}%`);
+            });
+            console.log();
+        });
+
+        return {
+            success: true,
+            data: filteredResults,
+            grouped: groupedBySource
+        };
+
+    } catch (error) {
+        console.error("Error in advanced search:", error);
+        return { success: false, message: error.message };
+    }
+}
+
+// Example usage
+advancedSearch("employee benefits", {
+    minSimilarity: 0.75,
+    maxResults: 5,
+    filterByType: "policy",
+    filterBySource: "hr_handbook"
+});
+```
+
+### Example 5: Building a Q&A System
+
+```javascript
+// Create an intelligent Q&A system using RAG storage
+async function answerQuestion(question) {
+    try {
+        console.log(`Question: ${question}\n`);
+
+        // Search for relevant context
+        const searchResult = await behindAPI.rag.V10.storage.search(question, 3);
+
+        if (!searchResult.success || searchResult.data.length === 0) {
+            return {
+                answer: "I couldn't find relevant information to answer this question.",
+                confidence: 0,
+                sources: []
+            };
+        }
+
+        // Get the most relevant result
+        const topResult = searchResult.data[0];
+        const confidence = topResult.similarity_score;
+
+        // Build response with sources
+        const sources = searchResult.data.map(result => ({
+            location: `${result.book_id}/${result.chapter_id}/${result.page_id}`,
+            type: result.doc_type,
+            relevance: (result.similarity_score * 100).toFixed(1) + "%"
+        }));
+
+        console.log(`Answer (${(confidence * 100).toFixed(1)}% confidence):`);
+        console.log(topResult.text);
+        console.log("\nSources:");
+        sources.forEach((source, idx) => {
+            console.log(`  ${idx + 1}. ${source.location} (${source.type}) - ${source.relevance} relevant`);
+        });
+
+        return {
+            answer: topResult.text,
+            confidence: confidence,
+            sources: sources,
+            allResults: searchResult.data
+        };
+
+    } catch (error) {
+        console.error("Error answering question:", error);
+        return {
+            answer: "An error occurred while processing your question.",
+            confidence: 0,
+            sources: []
+        };
+    }
+}
+
+// Example usage
+answerQuestion("What is the vacation policy?");
+answerQuestion("How does the code review process work?");
+answerQuestion("What happens during employee onboarding?");
+```
+
+---
+
+## Best Practices
+
+1. **Document Organization**: Use consistent and hierarchical naming for `bookId`, `chapterId`, and `pageId` to create a logical document structure. This makes it easier to filter and manage stored content.
+
+2. **Text Chunking**: Break large documents into smaller, focused chunks before storing. Optimal chunk size is typically 200-500 words for best semantic search results.
+
+3. **Metadata Consistency**: Maintain consistent `docType` and `source` values across your application to enable effective filtering and categorization.
+
+4. **Search Relevance**: Start with higher limit values and filter results by similarity score on the client side to ensure you capture all relevant content while maintaining quality.
+
+5. **Content Quality**: Store well-formatted, clear text for better embedding quality and search results. Remove unnecessary formatting characters and normalize whitespace.
+
+6. **Incremental Updates**: When updating documents, consider versioning by including version information in the `pageId` or storing timestamps in the text content.
+
+7. **Performance Optimization**: Cache frequently searched queries and their results to reduce API calls and improve response times.
+
+8. **Error Handling**: Always implement proper error handling, as network issues or storage failures can occur during document storage operations.
+
+---
+
+## Error Handling
+
+All methods return a response object with a `success` boolean property. When `success` is `false`, a `message` property will contain the error description.
+
+```javascript
+// Example error handling for search
+const searchResult = await behindAPI.rag.V10.storage.search("query", 5);
+
+if (!searchResult.success) {
+    console.error("Search failed:", searchResult.message);
+    // Handle the error appropriately
+    return;
+}
+
+// Process successful result
+const results = searchResult.data;
+
+// Example error handling for put
+const storeResult = await behindAPI.rag.V10.storage.put(
+    text,
+    docType,
+    source,
+    bookId,
+    chapterId,
+    pageId
+);
+
+if (!storeResult.success) {
+    console.error("Storage failed:", storeResult.message);
+    // Implement retry logic or alternative handling
+    return;
+}
+
+console.log("Document stored:", storeResult.data.document_id);
+```
+
+---
+
+## Integration Notes
+
+The RAG Storage API can be integrated with other EasyJob APIs to enhance functionality:
+
+- **Job Descriptions**: Store and search job descriptions for semantic matching with candidate profiles
+- **Applicant Profiles**: Index candidate resumes and profiles for intelligent talent search
+- **Company Documentation**: Build a searchable knowledge base of company policies, procedures, and guidelines
+- **Training Materials**: Create a semantic search system for training content and educational resources
+- **Support Systems**: Power Q&A and support systems with relevant document retrieval
+
+---
+
+## Technical Details
+
+### Vector Embeddings
+The RAG Storage API automatically generates vector embeddings for stored text using advanced language models. These embeddings capture semantic meaning, enabling intelligent search that understands context and intent rather than just keyword matching.
+
+### Semantic Search
+Search queries are converted to vector embeddings and compared against stored documents using cosine similarity. Results are ranked by semantic relevance, with scores ranging from 0 (unrelated) to 1 (highly relevant).
+
+### Language Support
+The system automatically detects and handles multiple languages, ensuring accurate semantic search across multilingual content.
+
+---
+
+## Use Cases
+
+1. **Knowledge Management**: Build internal knowledge bases with intelligent search capabilities
+2. **Content Recommendation**: Find and recommend related content based on user interests or current context
+3. **Document Classification**: Automatically categorize and organize documents based on content
+4. **Talent Matching**: Match job seekers with relevant positions based on semantic similarity of skills and requirements
+5. **Customer Support**: Power chatbots and support systems with relevant document retrieval
+6. **Research Assistance**: Help users find relevant research papers, articles, and documentation
+7. **Training Systems**: Create intelligent training platforms that surface relevant learning materials

package/example.js

@@ -0,0 +1,35 @@
+
+import BehindApiClient  from "./lib/behind-api-client/BehindApiClient.js";
+import BehindApiAuthClient from "./lib/behind-api-auth-client/BehindApiAuthClient.js";
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+(async () => {
+
+    let behindAuthAPI = new BehindApiAuthClient('https://api.auth.behind.ai');
+    let behindAPI = new BehindApiClient('https://api.behind.ai:6002', process.env.ACCESS_TOKEN);
+
+     behindAPI.selfsigned = true;
+
+    try{
+        try{
+            // let auth_result = await behindAuthAPI.authorisation.V10.code.createByEmail(
+            //     "test@behind.ai",
+            //     "app-easyjob",
+            //     process.env.APP_SECRET)
+            //
+            // console.log(auth_result);
+        } catch (e) {
+            console.log("Auth method exception:", e)
+        }
+
+        // let result = await behindAPI.easyjob.V10.companies.create("Company name");
+        //let result = await behindAPI.request('easyjob/10/companies/create', {name: "Company 3"});
+        let result_2 = await behindAPI.request('easyjob/10/companies/get_list', {});
+        console.log(result_2);
+    } catch (e) {
+        console.log("EXCEPTION",e)
+    }
+
+})()

package/index.cjs

@@ -0,0 +1,14 @@
+
+const BehindApiClient = require("./lib/behind-api-client/BehindApiClient.js");
+const BehindApiAuthClient = require("./lib/behind-api-auth-client/BehindApiAuthClient.js");
+
+(async () => {
+    // let behindAPI = new BehindApiClient('https://api.behind.ai:6002', 'token')
+    // behindAPI.selfsigned = true;
+    //
+    // let result = await behindAPI.easyjob.V10.companies.create("Company name-1");
+    // console.log(result);
+})()
+
+module.exports = BehindApiClient;
+module.exports = BehindApiAuthClient;

package/index.js

@@ -0,0 +1,15 @@
+
+import BehindApiClient  from "./lib/behind-api-client/BehindApiClient.js";
+
+(async () => {
+   // let behindAPI = new BehindApiClient('https://api.behind.ai:6002', 'token')
+   //  behindAPI.selfsigned = true;
+   //
+   // try{
+   //     let result = await behindAPI.easyjob.V10.companies.create("Company name");
+   //     console.log(result);
+   // } catch (e) {
+   //     console.log("EXCEPTION",e)
+   // }
+
+})()

package/lib/behind-api-auth-client/BehindApiAuthClient.js

@@ -0,0 +1,91 @@
+const axios = require('axios');
+const AuthorisationApp = require('./authorisation/AuthorisationApp');
+
+class BehindApiAuthClient {
+    constructor(endpoint, accessToken) {
+        this.endpoint = endpoint;
+        this.accessToken = accessToken;
+        this.selfsigned = false;
+        
+        // Event handlers
+        this.onExpiredHandler = () => {};
+        this.onRejectHandler = () => {};
+        this.onTooManyRequestsHandler = () => {};
+        
+        // Initialize app modules
+        this.authorisation = new AuthorisationApp(this);
+    }
+
+    onExpired(callback) {
+        if (typeof callback === 'function') {
+            this.onExpiredHandler = callback;
+        }
+    }
+
+    onReject(callback) {
+        if (typeof callback === 'function') {
+            this.onRejectHandler = callback;
+        }
+    }
+
+    onTooManyRequests(callback) {
+        if (typeof callback === 'function') {
+            this.onTooManyRequestsHandler = callback;
+        }
+    }
+
+    async apiRequest(app, version, module, action, data) {
+        let postData = {};
+        postData = Object.assign(postData, data);
+
+        const headers = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        };
+        
+        if (this.accessToken) {
+            postData.access_token = this.accessToken;
+            headers.AccessToken = this.accessToken;
+            headers.Authorization = `Bearer ${this.accessToken}`;
+        }
+
+        try {
+            let httpsAgent = null;
+            let options = { headers: headers };
+            
+            if (httpsAgent != null) {
+                options.httpsAgent = httpsAgent;
+            }
+
+            const response = await axios.post(
+                `${this.endpoint}/api/${app}/${version}/${module}/${action}`, 
+                postData, 
+                options
+            );
+
+            if (response.status === 200) {
+                if (response.data.success) {
+                    return response.data;
+                } else {
+                    throw response.status;
+                }
+            } else {
+                try {
+                    if (response.data.code === 1001 || response.data.code === 1009) {
+                        this.onRejectHandler(response.data);
+                    }
+                    if (response.data.code === 1039) {
+                        this.onTooManyRequestsHandler(response.data);
+                    }
+                } catch (e) {
+                    // Error handling callback failed
+                }
+                throw response.data.message;
+            }
+        } catch (e) {
+            throw e;
+        }
+    }
+}
+
+module.exports = BehindApiAuthClient;

package/lib/behind-api-auth-client/authorisation/AuthorisationApp.js

@@ -0,0 +1,9 @@
+const AuthorisationV10 = require('./AuthorisationV10');
+
+class AuthorisationApp {
+    constructor(apiClient) {
+        this.V10 = new AuthorisationV10(apiClient);
+    }
+}
+
+module.exports = AuthorisationApp;

package/lib/behind-api-auth-client/authorisation/AuthorisationV10.js

@@ -0,0 +1,9 @@
+const AuthorisationV10Code = require('./AuthorisationV10Code');
+
+class AuthorisationV10 {
+    constructor(apiClient) {
+        this.code = new AuthorisationV10Code(apiClient);
+    }
+}
+
+module.exports = AuthorisationV10;