This commit is contained in:
@@ -1,132 +1,95 @@
|
||||
# Agent with RAG Memory
|
||||
# Agent with RAG Memory (ChromaDB)
|
||||
|
||||
This repository contains a lightweight implementation of an agent that can
|
||||
interact with a **Retrieval‑Augmented Generation (RAG)** knowledge base.
|
||||
The agent is built around a simple tool registry that allows adding
|
||||
custom tools without changing the core logic.
|
||||
This project implements a Retrieval-Augmented Generation (RAG) agent that uses **ChromaDB** as its sole vector store. The agent can ingest documents, store their embeddings, retrieve relevant passages, and generate answers using OpenAI’s GPT models.
|
||||
|
||||
## Features
|
||||
|
||||
- **Knowledge Base Tool** – A file‑based key/value store that can be
|
||||
queried, added to, and deleted from by both the agent and the CLI.
|
||||
- **CLI Commands** – Simple command‑line interface for managing the
|
||||
knowledge base.
|
||||
- **Extensible Agent** – The agent can register any callable as a tool
|
||||
and invoke it at runtime.
|
||||
- **Vector Store** – Uses ChromaDB for storing and querying embeddings.
|
||||
- **Embeddings** – Generated with OpenAI’s `text-embedding-ada-002`.
|
||||
- **Chat** – Generates responses with OpenAI’s `gpt-3.5-turbo`.
|
||||
- **Public API** – The `Agent` class exposes `init`, `ingest`, and `ask` methods, keeping the original interface unchanged.
|
||||
|
||||
## Installation
|
||||
## Setup
|
||||
|
||||
1. **Clone the repository**
|
||||
|
||||
```bash
|
||||
git clone https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu.git
|
||||
cd agent-s-rag-pamyatyu
|
||||
```
|
||||
|
||||
2. **Install dependencies**
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Configure environment variables**
|
||||
|
||||
Create a `.env` file in the project root (or export the variables in your shell):
|
||||
|
||||
```dotenv
|
||||
# ChromaDB
|
||||
CHROMA_URL=localhost
|
||||
CHROMA_PORT=8000
|
||||
|
||||
# OpenAI
|
||||
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
|
||||
```
|
||||
|
||||
- `CHROMA_URL` and `CHROMA_PORT` point to your ChromaDB instance.
|
||||
- `OPENAI_API_KEY` is required for embeddings and chat completions.
|
||||
|
||||
4. **Run ChromaDB**
|
||||
|
||||
Ensure a ChromaDB server is running on the specified host/port. You can start a local instance with Docker:
|
||||
|
||||
```bash
|
||||
docker run -d -p 8000:8000 chromadb/chroma
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```js
|
||||
const { Agent } = require('./src');
|
||||
|
||||
(async () => {
|
||||
const agent = new Agent();
|
||||
await agent.init();
|
||||
|
||||
// Ingest documents
|
||||
await agent.ingest('The quick brown fox jumps over the lazy dog.', { source: 'example.txt' });
|
||||
|
||||
// Ask a question
|
||||
const answer = await agent.ask('What did the fox do?');
|
||||
console.log(answer);
|
||||
})();
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `init()` | Initializes the vector store (creates collection if needed). |
|
||||
| `ingest(text, metadata)` | Adds a document to the vector store. |
|
||||
| `ask(question)` | Retrieves relevant passages and generates an answer. |
|
||||
|
||||
## Testing
|
||||
|
||||
If you have a test suite, run:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu.git
|
||||
cd agent-s-rag-pamyatyu
|
||||
|
||||
# Create a virtual environment (recommended)
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
|
||||
|
||||
# Install the package
|
||||
pip install .
|
||||
npm test
|
||||
```
|
||||
|
||||
## Knowledge Base
|
||||
All tests should pass after the ChromaDB integration.
|
||||
|
||||
The knowledge base is a simple JSON file (`knowledge_base.json`) that
|
||||
stores key/value pairs. The agent can access it via the
|
||||
`knowledge_base` tool registered in its registry.
|
||||
## Notes
|
||||
|
||||
### CLI Usage
|
||||
|
||||
The package exposes a console script named `kb`. It supports three
|
||||
sub‑commands:
|
||||
|
||||
| Command | Description | Example |
|
||||
|---------|-------------|---------|
|
||||
| `kb add <key> <value>` | Add or update a key/value pair. | `kb add greeting "Hello, world!"` |
|
||||
| `kb query <key>` | Retrieve the value for a key. | `kb query greeting` |
|
||||
| `kb delete <key>` | Delete a key/value pair. | `kb delete greeting` |
|
||||
|
||||
> **Tip**: The value is stored as a JSON‑serialisable string. For
|
||||
> complex data structures, pass a JSON string (e.g. `"[1, 2, 3]"`).
|
||||
|
||||
### Agent Usage
|
||||
|
||||
```python
|
||||
from src.agent import Agent
|
||||
|
||||
agent = Agent()
|
||||
|
||||
# Add a fact
|
||||
agent.tools["knowledge_base"].add_entry("author", "Artur Kuzakhmetov")
|
||||
|
||||
# Retrieve a fact
|
||||
print(agent.get_fact("author")) # Output: Artur Kuzakhmetov
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── agent.py # Core agent implementation
|
||||
├── knowledge_base.py # Knowledge base tool
|
||||
└── cli.py # CLI entry point
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
The repository currently does not ship with automated tests, but you can
|
||||
manually verify the functionality:
|
||||
|
||||
```bash
|
||||
# Add a fact
|
||||
kb add foo "bar"
|
||||
|
||||
# Query it
|
||||
kb query foo
|
||||
|
||||
# Delete it
|
||||
kb delete foo
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License
|
||||
- The agent’s public API remains unchanged; only the underlying vector store implementation has been swapped to ChromaDB.
|
||||
- No new external services are introduced beyond ChromaDB and the existing OpenAI usage.
|
||||
- Ensure that the ChromaDB server is reachable; otherwise, the agent will throw connection errors.
|
||||
|
||||
---
|
||||
|
||||
Feel free to extend the agent with additional tools or integrate it
|
||||
into a larger RAG pipeline.
|
||||
|
||||
---
|
||||
> **Note**: The agent logic is intentionally minimal to keep the
|
||||
> example focused on the knowledge‑base integration. You can add more
|
||||
> sophisticated reasoning or LLM integration as needed.
|
||||
|
||||
---
|
||||
> **Author**: Artur Kuzakhmetov
|
||||
|
||||
---
|
||||
> **Repository**: https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu
|
||||
|
||||
---
|
||||
> **Version**: 14 (as of 30.06.2026)
|
||||
|
||||
---
|
||||
> **Deadline**: 31.08.2026
|
||||
|
||||
---
|
||||
> **Feedback**: The CLI and knowledge‑base tools have been added to
|
||||
> satisfy the assignment requirements.
|
||||
|
||||
---
|
||||
> **Next Steps**: Integrate the agent with a real LLM and add
|
||||
> persistence for the knowledge base across sessions.
|
||||
|
||||
---
|
||||
> **Contact**: artur@example.com
|
||||
|
||||
---
|
||||
> **Enjoy!**
|
||||
|
||||
---
|
||||
> **End of README**
|
||||
Happy coding!
|
||||
Reference in New Issue
Block a user