dataknobs-bots 0.2.4__py3-none-any.whl

dataknobs_bots-0.2.4.dist-info/METADATA

@@ -0,0 +1,591 @@
+Metadata-Version: 2.4
+Name: dataknobs-bots
+Version: 0.2.4
+Summary: Configuration-driven AI agents for DataKnobs
+Author-email: Spence Koehler <KoehlerSB747@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: dataknobs-common>=1.0.1
+Requires-Dist: dataknobs-config>=0.2.0
+Requires-Dist: dataknobs-data>=0.3.1
+Requires-Dist: dataknobs-fsm>=0.1.2
+Requires-Dist: dataknobs-llm>=0.1.0
+Requires-Dist: dataknobs-xization>=1.1.0
+Description-Content-Type: text/markdown
+
+# DataKnobs Bots
+
+**Configuration-driven AI agents and chatbots for the DataKnobs ecosystem**
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Overview
+
+DynaBot is a flexible, configuration-driven framework for building AI agents and chatbots. It provides a complete solution for multi-tenant AI deployments with features like memory management, knowledge retrieval (RAG), tool integration, and advanced reasoning strategies.
+
+### Key Features
+
+- **Configuration-First Design** - Define bot behavior entirely through YAML/JSON configuration
+- **Multi-Tenant Architecture** - Single bot instance serves multiple clients with isolated conversations
+- **Flexible Memory Systems** - Buffer, summary, and vector memory implementations
+- **RAG Support** - Built-in knowledge base with document chunking and vector search
+- **Tool Integration** - Load and configure tools from configuration without code changes
+- **Reasoning Strategies** - Simple, Chain-of-Thought, and ReAct reasoning
+- **Ecosystem Integration** - Seamlessly integrates with dataknobs-config, dataknobs-llm, dataknobs-data, and dataknobs-xization
+- **Stateless Design** - Perfect for horizontal scaling in containerized environments
+- **Production Ready** - PostgreSQL storage, error handling, and logging
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Documentation](#documentation)
+- [Development](#development)
+- [License](#license)
+
+## Installation
+
+Install using pip or uv:
+
+```bash
+# Using pip
+pip install dataknobs-bots
+
+# Using uv
+uv pip install dataknobs-bots
+```
+
+### Optional Dependencies
+
+For specific features, install optional dependencies:
+
+```bash
+# PostgreSQL storage
+pip install dataknobs-bots[postgres]
+
+# Vector memory with FAISS
+pip install dataknobs-bots[faiss]
+
+# All optional dependencies
+pip install dataknobs-bots[all]
+```
+
+## Quick Start
+
+### Simple Chatbot
+
+Create a basic chatbot with memory:
+
+```python
+import asyncio
+from dataknobs_bots import DynaBot, BotContext
+
+async def main():
+    # Configuration
+    config = {
+        "llm": {
+            "provider": "ollama",
+            "model": "gemma3:1b",
+            "temperature": 0.7,
+            "max_tokens": 1000
+        },
+        "conversation_storage": {
+            "backend": "memory"
+        },
+        "memory": {
+            "type": "buffer",
+            "max_messages": 10
+        }
+    }
+
+    # Create bot from configuration
+    bot = await DynaBot.from_config(config)
+
+    # Create conversation context
+    context = BotContext(
+        conversation_id="conv-001",
+        client_id="demo-client",
+        user_id="user-123"
+    )
+
+    # Chat with the bot
+    response = await bot.chat("Hello! What can you help me with?", context)
+    print(f"Bot: {response}")
+
+    response = await bot.chat("Tell me about yourself", context)
+    print(f"Bot: {response}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### RAG Chatbot with Knowledge Base
+
+Create a bot with knowledge retrieval:
+
+```python
+config = {
+    "llm": {
+        "provider": "ollama",
+        "model": "gemma3:1b"
+    },
+    "conversation_storage": {
+        "backend": "memory"
+    },
+    "knowledge_base": {
+        "enabled": True,
+        "documents_path": "./docs",
+        "vector_store": {
+            "backend": "faiss",
+            "dimension": 384
+        },
+        "embedding_provider": "ollama",
+        "embedding_model": "nomic-embed-text"
+    }
+}
+
+bot = await DynaBot.from_config(config)
+```
+
+### ReAct Agent with Tools
+
+Create an agent that can use tools:
+
+```python
+config = {
+    "llm": {
+        "provider": "ollama",
+        "model": "phi3:mini"
+    },
+    "conversation_storage": {
+        "backend": "memory"
+    },
+    "reasoning": {
+        "strategy": "react",
+        "max_iterations": 5,
+        "verbose": True
+    },
+    "tools": [
+        {
+            "class": "my_tools.CalculatorTool",
+            "params": {"precision": 2}
+        }
+    ]
+}
+
+bot = await DynaBot.from_config(config)
+```
+
+## Environment-Aware Configuration
+
+DynaBot supports **environment-aware configuration** for deploying the same bot across different environments. This separates portable bot behavior from environment-specific infrastructure.
+
+### Portable Bot Configs
+
+Bot configs use **logical resource references** instead of hardcoded infrastructure:
+
+```yaml
+# config/bots/assistant.yaml - PORTABLE
+bot:
+  llm:
+    $resource: default          # Logical name
+    type: llm_providers         # Resource type
+    temperature: 0.7            # Behavioral setting
+
+  conversation_storage:
+    $resource: conversations
+    type: databases
+```
+
+### Environment-Specific Bindings
+
+Environment configs define concrete implementations:
+
+```yaml
+# config/environments/development.yaml
+name: development
+resources:
+  llm_providers:
+    default:
+      provider: ollama
+      model: qwen3:8b
+  databases:
+    conversations:
+      backend: memory
+
+# config/environments/production.yaml
+name: production
+resources:
+  llm_providers:
+    default:
+      provider: openai
+      model: gpt-4
+      api_key: ${OPENAI_API_KEY}
+  databases:
+    conversations:
+      backend: postgres
+      connection_string: ${DATABASE_URL}
+```
+
+### Resolving Resources
+
+```python
+from dataknobs_config import EnvironmentConfig
+from dataknobs_bots.config import BotResourceResolver
+
+# Auto-detects environment from DATAKNOBS_ENVIRONMENT
+env = EnvironmentConfig.load()
+resolver = BotResourceResolver(env)
+
+# Get initialized resources
+llm = await resolver.get_llm("default")
+db = await resolver.get_database("conversations")
+```
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#environment-aware-configuration) for complete documentation.
+
+## Core Concepts
+
+### DynaBot
+
+The main bot class that orchestrates all components. Created from configuration and handles:
+- Message processing
+- Conversation management
+- Memory integration
+- Knowledge retrieval
+- Tool execution
+- Reasoning strategies
+
+### BotContext
+
+Encapsulates execution context for each bot interaction:
+- `conversation_id` - Unique ID for the conversation
+- `client_id` - Tenant/client identifier
+- `user_id` - User identifier
+- `session_metadata` - Additional metadata
+
+### Memory Systems
+
+Three types of memory for context management:
+
+1. **Buffer Memory** - Simple sliding window of recent messages
+2. **Summary Memory** - Compressed summaries of conversation history
+3. **Vector Memory** - Semantic search over conversation history
+
+### Knowledge Base (RAG)
+
+Retrieval Augmented Generation support with:
+- Document ingestion and chunking
+- Vector embeddings
+- Semantic search
+- Context injection
+
+### Reasoning Strategies
+
+1. **Simple** - Direct LLM response
+2. **Chain-of-Thought** - Step-by-step reasoning
+3. **ReAct** - Reasoning + Acting with tools
+
+### Tools
+
+Tools extend bot capabilities with external functions. Loaded from configuration:
+
+```python
+"tools": [
+    # Direct instantiation
+    {
+        "class": "my_tools.CalculatorTool",
+        "params": {"precision": 3}
+    },
+    # XRef to predefined tool
+    "xref:tools[my_calculator]"
+]
+```
+
+## Configuration
+
+DynaBot uses a configuration-first approach. All bot behavior is defined through configuration.
+
+### Basic Configuration Structure
+
+```yaml
+# LLM Configuration
+llm:
+  provider: ollama
+  model: gemma3:1b
+  temperature: 0.7
+  max_tokens: 1000
+
+# Conversation Storage
+conversation_storage:
+  backend: memory  # or postgres
+
+# Optional: Memory
+memory:
+  type: buffer
+  max_messages: 10
+
+# Optional: Knowledge Base
+knowledge_base:
+  enabled: true
+  documents_path: ./docs
+  vector_store:
+    backend: faiss
+    dimension: 384
+  embedding_provider: ollama
+  embedding_model: nomic-embed-text
+
+# Optional: Reasoning
+reasoning:
+  strategy: react
+  max_iterations: 5
+  verbose: true
+
+# Optional: Tools
+tools:
+  - class: my_tools.CalculatorTool
+    params:
+      precision: 2
+
+# Optional: System Prompt
+prompts:
+  helpful_assistant: "You are a helpful AI assistant."
+
+system_prompt:
+  name: helpful_assistant
+```
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for complete configuration reference.
+
+## Examples
+
+The `examples/` directory contains working examples demonstrating various features:
+
+1. **Simple Chatbot** (`01_simple_chatbot.py`) - Basic conversational bot
+2. **Chatbot with Memory** (`02_chatbot_with_memory.py`) - Buffer memory for context
+3. **RAG Chatbot** (`03_rag_chatbot.py`) - Knowledge base integration
+4. **ReAct Agent** (`04_react_agent.py`) - Tool-using agent with reasoning
+5. **Multi-Tenant Bot** (`05_multi_tenant.py`) - Multiple clients, isolated conversations
+6. **Config-Based Tools** (`06_config_based_tools.py`) - Configuration-driven tool loading
+
+### Running Examples
+
+All examples use Ollama for local LLM inference:
+
+```bash
+# Install Ollama: https://ollama.ai/
+
+# Pull required models
+ollama pull gemma3:1b
+ollama pull phi3:mini
+ollama pull nomic-embed-text
+
+# Run an example
+python examples/01_simple_chatbot.py
+```
+
+See [examples/README.md](examples/README.md) for detailed information on each example.
+
+## Documentation
+
+### User Documentation
+
+- [User Guide](docs/USER_GUIDE.md) - Tutorials and how-to guides
+- [Configuration Reference](docs/CONFIGURATION.md) - Complete configuration options
+- [Environment-Aware Configuration](docs/CONFIGURATION.md#environment-aware-configuration) - Portable configs for multi-environment deployments
+- [Migration Guide](docs/MIGRATION.md) - Migrate existing configs to environment-aware pattern
+- [Tools Development](docs/TOOLS.md) - Creating and configuring tools
+
+### Developer Documentation
+
+- [API Reference](docs/API.md) - Complete API documentation
+- [Architecture](docs/ARCHITECTURE.md) - System design and components
+- [Examples](examples/README.md) - Working code examples
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/kbs-labs/dataknobs.git
+cd dataknobs/packages/bots
+
+# Install dependencies with development extras
+uv pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=dataknobs_bots --cov-report=html
+
+# Run specific test file
+pytest tests/unit/test_dynabot.py
+
+# Run integration tests (requires Ollama)
+TEST_OLLAMA=true pytest tests/integration/
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+
+# Lint code
+ruff check src/ tests/
+
+# Type checking
+mypy src/
+```
+
+### Project Structure
+
+```
+packages/bots/
+├── src/dataknobs_bots/
+│   ├── bot/              # Core bot implementation
+│   │   ├── base.py       # DynaBot class
+│   │   ├── context.py    # BotContext class
+│   │   └── registry.py   # Bot registry
+│   ├── memory/           # Memory implementations
+│   │   ├── base.py       # Memory interface
+│   │   ├── buffer.py     # Buffer memory
+│   │   └── vector.py     # Vector memory
+│   ├── knowledge/        # RAG implementation
+│   │   └── rag.py        # Knowledge base
+│   ├── reasoning/        # Reasoning strategies
+│   │   ├── base.py       # Reasoning interface
+│   │   ├── simple.py     # Simple reasoning
+│   │   └── react.py      # ReAct reasoning
+│   ├── tools/            # Built-in tools
+│   │   └── knowledge_search.py
+│   └── utils/            # Utilities
+├── tests/
+│   ├── unit/             # Unit tests
+│   ├── integration/      # Integration tests
+│   └── fixtures/         # Test fixtures
+├── examples/             # Working examples
+├── docs/                 # Documentation
+└── README.md             # This file
+```
+
+## Use Cases
+
+### Customer Support Bot
+
+Multi-tenant bot with knowledge base for customer support:
+
+```python
+config = {
+    "llm": {"provider": "openai", "model": "gpt-4"},
+    "conversation_storage": {"backend": "postgres"},
+    "memory": {"type": "buffer", "max_messages": 20},
+    "knowledge_base": {
+        "enabled": True,
+        "documents_path": "./support_docs"
+    }
+}
+```
+
+### Personal Assistant
+
+Agent with tools for task automation:
+
+```python
+config = {
+    "llm": {"provider": "anthropic", "model": "claude-3-sonnet"},
+    "reasoning": {"strategy": "react"},
+    "tools": [
+        {"class": "tools.CalendarTool", "params": {}},
+        {"class": "tools.EmailTool", "params": {}},
+        {"class": "tools.WeatherTool", "params": {}}
+    ]
+}
+```
+
+### Document Q&A
+
+RAG-powered document question answering:
+
+```python
+config = {
+    "llm": {"provider": "ollama", "model": "llama3.1:8b"},
+    "knowledge_base": {
+        "enabled": True,
+        "documents_path": "./company_docs",
+        "chunking": {"max_chunk_size": 500, "chunk_overlap": 50}
+    }
+}
+```
+
+## Performance Considerations
+
+### Scaling
+
+- **Stateless Design** - Each request is independent, enabling horizontal scaling
+- **Connection Pooling** - PostgreSQL connection pooling for high concurrency
+- **Caching** - In-memory conversation caching reduces database queries
+- **Async/Await** - Fully asynchronous for high throughput
+
+### Optimization Tips
+
+1. **Use Buffer Memory** - Faster than vector memory for most use cases
+2. **Limit Memory Window** - Keep `max_messages` reasonable (10-20)
+3. **PostgreSQL for Production** - Don't use in-memory storage in production
+4. **Batch Knowledge Base Indexing** - Index documents offline
+5. **Use Local LLMs** - Ollama for reduced latency and cost
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/kbs-labs/dataknobs/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/kbs-labs/dataknobs/discussions)
+- **Documentation**: [docs/](docs/)
+- **Examples**: [examples/](examples/)
+
+## Acknowledgments
+
+Built on the DataKnobs ecosystem:
+- [dataknobs-config](../config/) - Configuration management
+- [dataknobs-llm](../llm/) - LLM providers and tools
+- [dataknobs-data](../data/) - Data storage backends
+- [dataknobs-xization](../xization/) - Configuration resolution
+
+## Roadmap
+
+- [ ] Streaming responses
+- [ ] Multi-modal support (images, audio)
+- [ ] Advanced memory strategies (hybrid, hierarchical)
+- [ ] Tool marketplace
+- [ ] Web UI for bot management
+- [ ] Performance monitoring and analytics
+- [ ] A/B testing framework
+- [ ] Voice interface support
+
+---
+
+Made with ❤️ by the DataKnobs team

dataknobs_bots-0.2.4.dist-info/RECORD

@@ -0,0 +1,42 @@
+dataknobs_bots/__init__.py,sha256=h_PqsqssRQm0-oQeDBUSNMnqB5Tpun6o1s_VlbveJRw,1067
+dataknobs_bots/api/__init__.py,sha256=Vf32_1KWpUvFr7_jYpZ12zjrosj5UdZpX8QYc6jV1Ew,920
+dataknobs_bots/api/dependencies.py,sha256=3mkNzVgfqD-n7wsCLxYhTjuJ6uDIPua1FT2AJ1su8z0,3689
+dataknobs_bots/api/exceptions.py,sha256=BO0qBCjRc0FDkK4WtPpcPCZeI6WX7Ib7DOAOPbanGBI,8040
+dataknobs_bots/bot/__init__.py,sha256=NylKgjrImE8f15nR2Gkfxyze9fLbz0zZZT5ERkrk7Pw,339
+dataknobs_bots/bot/base.py,sha256=DWJ-cSvuthkJ0ARVLhpoUUJFFDXaIyo0lW2NOHZLaXo,42984
+dataknobs_bots/bot/context.py,sha256=PW8UD27N_j5eWGSp90x9KgPNdtyZ0lq5ri6adI754NY,3215
+dataknobs_bots/bot/manager.py,sha256=IFShheQbQMdrPyoGqpkeJwFxYiD9uEocNVlgskhQ5uQ,15153
+dataknobs_bots/bot/registry.py,sha256=IYaMZzUDzk74U-De8RdJ9zry1jBCcpRtKcXeYxm37YY,20828
+dataknobs_bots/config/__init__.py,sha256=ua6XCJR3EcdVZi56qtKIFvLcU3HZuDLvKn4fJzshKt8,1140
+dataknobs_bots/config/resolution.py,sha256=HSGz15jr_SfIjk81pVez4_381frMreHv2JpfIB9Qt4I,11074
+dataknobs_bots/knowledge/__init__.py,sha256=ckeFPWexTPOl-ah8S5uwjofnprreKdhHdOQMC0AKJmE,2164
+dataknobs_bots/knowledge/rag.py,sha256=UnUjvpvFDrsPxj51IusVB60xQca2d7fdeQXGSCjkSGI,25666
+dataknobs_bots/knowledge/query/__init__.py,sha256=4tNAx1LQdp96pbMqe7r_PQj7lhxHtScJ3g4Ui0Oovqc,595
+dataknobs_bots/knowledge/query/expander.py,sha256=hUreBchr0ljQgE6Qi2UCf53x5_AzGUhQvOiY3WCSHL4,8162
+dataknobs_bots/knowledge/query/transformer.py,sha256=Ah7ulsRd0F-BWyRF_U5_ZHOFUhiy3AetfpvADtW0HjA,8746
+dataknobs_bots/knowledge/retrieval/__init__.py,sha256=7xxdwoBzpsPcCR77SUYMPIbtLMLwnzVz7DsZENyPRwI,532
+dataknobs_bots/knowledge/retrieval/formatter.py,sha256=F9PD6cs7P-H-RKY3YDNWkxquFnSeV-eI8W4n5otkqfE,7942
+dataknobs_bots/knowledge/retrieval/merger.py,sha256=25lHca_2oA1g4o_WNSiOJOHz_H7PVFUyfSLdctocmMk,8922
+dataknobs_bots/memory/__init__.py,sha256=oNhToZM8SkBd3REeih9HtT7UKsv_f6xmKu6bEUYhqEU,1493
+dataknobs_bots/memory/base.py,sha256=7iG1JN3mqqaDAptJKJgfuHIQy6gh6qRmsVYBF1ow5xI,1000
+dataknobs_bots/memory/buffer.py,sha256=LI65dxa9EI3WthsSqT6vFVz4CwUXsDdVgRykUUt6Fw8,1759
+dataknobs_bots/memory/vector.py,sha256=8pr2EZSCjiG_dgKslHewAtLw0xeftcf6vSYVoUIvO1E,6768
+dataknobs_bots/middleware/__init__.py,sha256=L705nKGPw9aHTEWHh2-j4gcmfR-oZa60BVzJA_dTEHU,262
+dataknobs_bots/middleware/base.py,sha256=pVfoRIxpcjrIWsDtQjJVBNBLoIbtNUg44Gl4wThbBMc,3027
+dataknobs_bots/middleware/cost.py,sha256=3QYet98p_3g8DDbCXtSBh9Zad0X-2lqdjRB2Y0qdmlg,14520
+dataknobs_bots/middleware/logging.py,sha256=SyDEaO_8TrebMRZ58imrBgGRp8XYqoX1npvgiWYwMho,6303
+dataknobs_bots/reasoning/__init__.py,sha256=TIl2Ny2tmDk0DuELSaro-PI8bbIurlE6w3h3y-1Y70g,1881
+dataknobs_bots/reasoning/base.py,sha256=y51YacVhCZzNB2j3qr7E0u-6cm94EiiM2k5QpYBLeAs,1407
+dataknobs_bots/reasoning/react.py,sha256=5iU8KKLXA-ytjEEDvP_opgp0E1WyLGlDON7jVtFsVAQ,10249
+dataknobs_bots/reasoning/simple.py,sha256=TtF5Sf8qc_7G4R-nFTEhRaRkMyblK1B4135a6UtCWCU,1457
+dataknobs_bots/registry/__init__.py,sha256=lvZ5DcsKtpNWT2qBdRL9gyR89ZsItgXrHON6ZWAVRvk,1039
+dataknobs_bots/registry/backend.py,sha256=9Li1eMc_Z9pacSnj4F7tPlJLtSyNTbYFNtPyCusDcb4,4693
+dataknobs_bots/registry/memory.py,sha256=ADwYje7wALmjPVL596zTXjaXKG2Nm1vsrtuBblo0nOc,7097
+dataknobs_bots/registry/models.py,sha256=lYHUqvSvN7_jbJBKNWUyllEhO_B8LKbrqYruz8KHtUk,3370
+dataknobs_bots/registry/portability.py,sha256=BnYjayDQhHZcoBxOQrsMi4yfWF7Jkt5Pqz6azeOor8w,6554
+dataknobs_bots/tools/__init__.py,sha256=Gmj8Nek0BJZ0vRnPL01bBlgaX9WW2oxhhgBKCHW2WrM,111
+dataknobs_bots/tools/knowledge_search.py,sha256=wBo5wJ3s3kOUoWKyECNxWaCuvqy3BMtgQ6j0DZTk1LA,3505
+dataknobs_bots/utils/__init__.py,sha256=n8CLFPBgKbuHmPMc5-yioYScNXpM5a8JtRt-sJawDjs,68
+dataknobs_bots-0.2.4.dist-info/METADATA,sha256=0IxJUWdG_skKG0wSu6xufuZg_yDW-NN37EmmsmKC5vo,15373
+dataknobs_bots-0.2.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dataknobs_bots-0.2.4.dist-info/RECORD,,

dataknobs_bots-0.2.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any