@team-bitbot/core

> P-MACS Core SDK - Pharmacy Management and Control System with AI-powered LangChain Tools


A comprehensive TypeScript SDK for hospital pharmacy management featuring 27 LangChain-powered AI tools for inventory management, expiry tracking, forecasting, analytics, and procurement.

✨ Features

- 🤖 27 AI-Powered Tools - LangChain-integrated tools for pharmacy operations
- 📦 Inventory Management - Real-time stock tracking with safety stock alerts
- ⏰ Expiry Tracking - FEFO (First Expiry First Out) recommendations
- 📊 Analytics - Top/slow movers, usage patterns, seasonal trends
- 🔮 Forecasting - Predictive analytics for stock-out prevention
- 💰 Procurement - Automated purchase order generation
- 🔒 Role-Based Access - Nurse, Pharmacist, and Admin permissions
- 📈 100% Test Coverage - All 235 tests passing

📦 Installation

``bash
npm install @team-bitbot/core @langchain/core @langchain/openai langchain
`

$3

This package requires the following peer dependencies:

`json
{
"@langchain/core": "^0.3.0",
"@langchain/openai": "^0.3.0",
"langchain": "^0.3.0"
}
`

🚀 Quick Start

`typescript
import { createAllTools, CSVDatabaseAdapter } from '@team-bitbot/core';

// Initialize database adapter
const db = new CSVDatabaseAdapter('./data');

// Create tools for a pharmacist user
const tools = createAllTools({
db: db,
userRole: 'Pharmacist',
userId: 'P001'
});

// Use tools with LangChain
import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatPromptTemplate } from '@langchain/core/prompts';

const llm = new ChatOpenAI({
modelName: 'gpt-4o',
temperature: 0
});

const prompt = ChatPromptTemplate.fromMessages([
['system', 'You are a pharmacy management assistant.'],
['human', '{input}'],
['placeholder', '{agent_scratchpad}'],
]);

const agent = await createOpenAIFunctionsAgent({
llm,
tools,
prompt,
});

const executor = new AgentExecutor({
agent,
tools,
});

const result = await executor.invoke({
input: 'What drugs are expiring in the next 30 days?'
});

console.log(result.output);
`

🛠️ Available Tools

$3


- get_full_inventory - Complete inventory overview with filters
- lookup_inventory - Search specific drugs
- update_inventory - Modify stock levels
- list_ward_stock - View ward-specific inventory
- get_location_list - List all storage locations
- get_transaction_history - Audit trail
- manage_user_access - User permissions (Admin only)
- And more...

$3

- check_expiring_drugs - Find drugs nearing expiry
- get_fefo_recommendations - First Expiry First Out guidance
- get_expired_items_report - Generate expiry reports
- get_batch_report - Batch-specific expiry tracking

$3

- get_top_movers_report - High-usage drugs
- get_slow_movers_report - Low-usage drugs with financial impact
- get_usage_analytics - Usage patterns
- get_shortage_alerts - Stock-out warnings
- get_stockout_risk_report - Risk assessments
- get_restock_recommendation - Automated reorder suggestions

$3

- detect_seasonal_patterns - Identify usage trends
- predict_stockout_date - Forecast stock depletion
- recalculate_all_safety_stocks - Dynamic safety stock optimization

$3

- generate_purchase_order - Automated PO generation
- estimate_order_value - Budget planning
- And more...

📚 Core Concepts

$3

`typescript
import { CSVDatabaseAdapter, CachedDatabaseAdapter } from '@team-bitbot/core';

// Basic CSV adapter
const baseDb = new CSVDatabaseAdapter('./data');

// Cached adapter for better performance
const db = new CachedDatabaseAdapter(baseDb);
`

$3

`typescript
import { getToolsByPermission } from '@team-bitbot/core';

const allTools = createAllTools({ db, userRole: 'Nurse', userId: 'N001' });

// Filter tools by role
const nurseTools = getToolsByPermission(allTools, 'Nurse'); // 8 tools
const pharmacistTools = getToolsByPermission(allTools, 'Pharmacist'); // 22 tools
const adminTools = getToolsByPermission(allTools, 'Admin'); // 27 tools
`

$3

`typescript
import type { EnrichedInventoryItem, Transaction } from '@team-bitbot/core';

// Enriched inventory with computed fields
interface EnrichedInventoryItem {
drugId: string;
drugName: string;
qtyOnHand: number;
safetyStock: number;
status: 'adequate' | 'low' | 'critical' | 'stockout' | 'expired';
category: 'controlled' | 'standard' | 'refrigerated';
daysRemaining: number | null;
avgDailyUse: number;
// ... and more
}
`

🎯 Use Cases

$3

`typescript
const expiringTool = tools.find(t => t.name === 'check_expiring_drugs');
const result = await expiringTool.invoke({ days: 30 });
const data = JSON.parse(result);

console.log(Found ${data.summary.totalExpiring} drugs expiring in 30 days);
data.expiringDrugs.forEach(drug => {
console.log(${drug.drugName} at ${drug.location}: ${drug.daysRemaining} days);
});
`

$3

`typescript
const alertsTool = tools.find(t => t.name === 'get_shortage_alerts');
const result = await alertsTool.invoke({});
const data = JSON.parse(result);

if (data.alertLevel === 'critical') {
console.log(URGENT: ${data.summary.criticalShortages} critical shortages!);
}
`

$3

`typescript
const topMoversTool = tools.find(t => t.name === 'get_top_movers_report');
const result = await topMoversTool.invoke({ days: 30, topN: 10 });
const data = JSON.parse(result);

data.topMovers.forEach(drug => {
console.log(${drug.rank}. ${drug.drugName}: ${drug.avgDailyUsage} units/day);
});
`

🧪 Testing

The package includes comprehensive tests with 100% pass rate:

`bash
npm test # Run all tests
npm run test:watch # Watch mode
`

Test Coverage:
- 24 test files
- 235 tests passing
- 100% pass rate

📖 API Reference

$3

`typescript
// Database Adapters
export { CSVDatabaseAdapter } from './database/CSVAdapter';
export { CachedDatabaseAdapter } from './database/CachedAdapter';

// Tool Creation
export { createAllTools, getToolsByPermission } from './tools';

// Types
export type { DatabaseAdapter } from './database/CSVAdapter';
export type { EnrichedInventoryItem, Transaction, User } from './types';

// Utilities
export { enrichInventoryItem } from './database/models';
export { detectSeasonality, calculateSafetyStock } from './utils/forecasting';
`

$3

`typescript
// Tools only
import { createAllTools } from '@team-bitbot/core/tools';

// Database only
import { CSVDatabaseAdapter } from '@team-bitbot/core/database';
`

🔧 Configuration

$3

`
data/
├── inventory_master.csv # Main inventory
├── transaction_logs.csv # Transaction history
├── user_access.csv # User accounts
├── access_logs.csv # Audit logs
└── archived_logs/ # Historical data
`

$3

inventory_master.csv:
`csv
drug_id,drug_name,location,qty_on_hand,safety_stock,unit_cost,expiry_date,batch_lot
D001,Paracetamol,Main-Pharmacy,500,100,0.50,2025-12-31,BATCH001
`

transaction_logs.csv:
`csv
txn_id,timestamp,drug_id,action,qty_change,location,emp_id,notes
T001,2024-01-15T10:30:00Z,D001,USE,-10,ICU,N001,Patient dispensing
`

🌟 Advanced Features

$3

Implement your own database backend:

`typescript
import type { DatabaseAdapter } from '@team-bitbot/core';

class MySQLAdapter implements DatabaseAdapter {
async loadInventory() {
// Your MySQL query
}

async loadTransactions(days: number) {
// Your implementation
}

// ... implement all methods
}
`

$3

Built-in caching for performance:

`typescript
import { CachedDatabaseAdapter } from '@team-bitbot/core';

const cachedDb = new CachedDatabaseAdapter(baseDb);
// Automatic 5-minute cache for inventory and transactions
`

$3

`typescript
import { PasswordHasher } from '@team-bitbot/core/auth';

const hasher = new PasswordHasher();
const hashed = await hasher.hash('password123');
const isValid = await hasher.verify('password123', hashed);
``

📊 Performance

- Package Size: 129 KB (gzipped)
- Unpacked Size: 659 KB
- Build Outputs: ESM + CJS + TypeScript definitions
- Tree-shakeable: Yes
- Side Effects: None

🤝 Contributing

Contributions welcome! This package powers critical healthcare operations, so we maintain high standards:

1. All tests must pass (100% required)
2. TypeScript strict mode
3. Comprehensive test coverage for new features
4. Clear documentation

📄 License

MIT License - see LICENSE file for details

🔗 Links

- GitHub Repository
- Issue Tracker
- Changelog

🙏 Acknowledgments

Built with:
- LangChain - AI framework
- OpenAI - GPT-4 integration
- TypeScript - Type safety
- Vitest - Testing framework

📞 Support

- 📧 Email: support@pmacs.dev
- 💬 Issues: GitHub Issues
- 📖 Docs: Full Documentation

---

Made with ❤️ for healthcare professionals worldwide