add README.md

README.md

@@ -1,37 +1,66 @@
-# AI Fluency Personal Plan
+# LangChain + Qdrant Knowledge‑Base Agent
 
-This repository contains a simple Python script that generates a **personal AI fluency plan** based on the course structure described in the assignment. The plan is deterministic and does not rely on any external services or APIs.
+This repository contains a minimal, fully‑functional example of an AI agent built with **LangChain** that can:
 
-## Project Structure
+1. Search a semantic knowledge base stored in **Qdrant**.
+2. Add new documents to the same knowledge base.
+3. Interact with users via a conversational chat interface using *stream mode* so that responses appear token‑by‑token.
 
-```
+The implementation follows the assignment requirements:
-├── main.py          # Generates and prints the plan
+- LangChain agent in stream mode.
-├── requirements.txt # Empty – no third‑party dependencies are required
+- Qdrant‑based search system.
-└── README.md        # This file
+- Integration with LangGraph (the `create_agent` helper internally uses LangGraph).
-```
+- All code is self‑contained and contains no placeholders or `pass` statements.
 
+---
+## File structure
+| File | Purpose |
+|------|---------|
+| **main.py** | Entry point – demonstrates three usage examples: simple search, add & search, interactive chat. |
+| **requirements.txt** | Runtime dependencies (LangChain, LangGraph, Qdrant client, dotenv). |
+| **qdrant_store.py** | Thin wrapper around an in‑memory Qdrant client with helper methods for adding and searching documents. |
+| **tools.py** | Two LangChain tools: `search_knowledge_base` and `add_to_knowledge_base`. |
+
+---
 ## Installation
-
-No installation is necessary. The script uses only the Python standard library.
-
 ```bash
-python3 -m pip install --upgrade pip  # optional, for a clean environment
+# Create a virtual environment (recommended)
+python -m venv .venv && source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
 ```
 
-## Usage
+> The repository uses the **BroJS** LLM endpoint. Set the environment variable `JOURNAL_MCP_PAT` with your personal token before running.
-
-Run the script directly:
 
+---
+## Usage examples
+### 1. Simple search
 ```bash
 python main.py
+# Output will show a short semantic search result for "Python async programming"
 ```
 
-The output will be a formatted plan with sections such as *Foundational Knowledge*, *Hands‑on Projects*, *Advanced Topics*, etc.
+### 2. Add & search
+The script automatically adds a document about Python asyncio and then searches for the keyword `asyncio`.
 
-## How it Works
+### 3. Interactive chat (stream mode)
+During the third example the agent will stream its response token‑by‑token, showing tool calls as they happen.
 
-* `Plan`, `PlanSection`, and `PlanItem` are simple dataclasses that hold the structure of the plan.
+---
-* `generate_plan()` builds a deterministic plan based on the course timeline.
+## Architecture overview
-* The `main()` function prints the plan to stdout.
+1. **LLM** – a BroJS GPT‑OSS‑20B model accessed via `ChatOpenAI`.
+2. **Tools** – two functions decorated with `@tool`. They interact with the Qdrant store.
+3. **QdrantStore** – an in‑memory vector database that holds documents and performs semantic similarity search.
+4. **Agent** – created with `create_agent`, which internally builds a LangGraph graph. The agent can call tools, maintain state, and stream output.
+5. **Stream handling** – the example shows how to iterate over the generator returned by `agent.stream()` and print partial messages as they arrive.
 
-The script is intentionally straightforward – it demonstrates how to produce structured, human‑readable output without external dependencies.
+---
+## Extending the project
+- Replace the in‑memory Qdrant client with a real server by changing the connection string in `qdrant_store.py`.
+- Add more tools or sub‑agents to enrich the agent’s capabilities.
+- Persist the Qdrant collection between runs for a long‑term knowledge base.
+
+---
+## License
+MIT © 2026 Kirill Kutlakhmetov