KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

LocalAgent

★ 119 Open GitHub ↗

Local Reasoning Agent using LangChain + Ollama

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

## Agent Kurama

A small local research agent that runs on your machine using LangChain + Ollama. It can search Wikipedia, DuckDuckGo, Arxiv, Crossref, Europe PMC, Open Library, check Unpaywall OA links, do quick math, keep notes in a local ChromaDB, pull in fresh news via AskNews, search Google via SerpAPI, search via SearxNG, and append segments to ongoing Markdown reports.

### What you get

- Local LLM chat (Ollama)
- Tools: wiki, duckduckgo, arxiv, crossref, europe_pmc, openlibrary, unpaywall (OA lookup), math, date
- Extras: serp_search (Google via SerpAPI), searx_search (SearxNG), save_md_plus (append to report)
- Memory: stores/retrieves snippets in a local ChromaDB folder
- Optional: AskNews for recent events (needs free API creds)
- Utilities: save markdown locally (`save_md_locally`) and summarize long text (`summarize_text`)

---

## Quick start

1. Prereqs

- macOS or Linux (Windows WSL is fine too)
   - Python 3.10+
   - Ollama installed and running

2. Install Ollama

- macOS (Homebrew):

```zsh
     brew install ollama
     ollama serve
     ```

- Or grab the app: https://ollama.com

3. Pull the models this project expects

- Chat model used in `agent.py`:

```zsh
     ollama pull gpt-oss:120b-cloud
     ```

- Embedding model used for memory in `retriever.py`:

```zsh
     ollama pull nomic-embed-text
     ```

Note: If `gpt-oss:120b-cloud` isn’t available on your system, you can swap it for a common model like `llama3:8b` or `qwen2:7b` by editing `agent.py`:

```python
   llm = ChatOllama(model="llama3:8b", temperature=0.7)
   ```

4. Set up the project

```zsh
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   ```

5. (Optional, but recommended) Add a .env for AskNews, polite headers, and optional web search tools

The agent imports the AskNews tool on startup. To avoid errors, add your free AskNews keys:

```env
   # .env
   ASKNEWS_CLIENT_ID=your_client_id
   ASKNEWS_CLIENT_SECRET=your_client_secret
   ```

Don’t want news? Temporarily remove `asknews_search` from the `tools=[...]` list in `agent.py` and the import `from tools.getNews import asknews_search`.

(Optional) To enable SerpAPI (Google) search, also add:

```env
   SERPAPI_API_KEY=your_serpapi_key
   ```

Don’t want SerpAPI? Remove `serp_search` from the `tools=[...]` list and the import `from tools.serpSearch import serp_search`.

(Optional) To enable SearxNG (self-hosted/private metasearch), add:

```env
   SEARX_INSTANCE_URL=https://your-searx-instance
   SEARX_TOP_K_RESULTS=5
   ```

Don’t want SearxNG? Remove `searx_search` from the `tools=[...]` list and the import `from tools.SearxNG import searx_search`.

(Optional but polite) To include an email contact in headers for Crossref/Unpaywall and satisfy Unpaywall's required email parameter:

```env
   CONTACT_EMAIL=you@example.com     # used in User-Agent
   UNPAYWALL_EMAIL=you@example.com   # used by unpaywall_lookup if inline email not provided
   ```

6. Run it

```zsh
   python agent.py
   ```

You’ll see a prompt:

```
   Ask Kurama 🦊
   ```

Kurama will Analyze -> Prompt -> Research -> Reason -> Gather Info -> Use Tools -> Save Report -> Preview Report

---

## What gets saved where

- Vector store lives in `./chromadb_store` (created automatically)
- You can wipe it by deleting that folder if you want a clean slate
- Markdown reports saved via the tool are in `./LocalStore` (created automatically)

Note on Linux/WSL: Previously, files could be written relative to the process working directory (sometimes `/tmp` or another launcher path). This has been fixed. Files now save under the project root `LocalStore` regardless of where the process starts.

- You can override the output directory explicitly by setting an environment variable:

```zsh
  export LOCALAGENT_OUTPUT_DIR=/absolute/path/where/you/want/reports
  ```

Both `save_md_locally` and `save_md_plus` respect this variable.

---

## Optional: run tests

There are a few quick tests under `tests/`.

```zsh
pip install -U pytest
pytest -k "not asknews"   # skip news tests if you didn’t set .env
```

---

## Troubleshooting

- “model not found” → make sure you ran `ollama pull gpt-oss:120b-cloud` and `ollama pull nomic-embed-text`. If `gpt-oss:120b-cloud` isn’t available, switch the model in `agent.py` to something you have (e.g., `llama3:8b`).
- “AskNews Error / Missing env” → add `ASKNEWS_CLIENT_ID` and `ASKNEWS_CLIENT_SECRET` to your `.env` or remove the AskNews tool from the agent.
- “Ollama not running” → start it with `ollama serve`. On macOS, the app can also run a background service.
- “Chroma DB issues” → delete the `chromadb_store` folder and try again.
- “Report saved but can’t find it” → the save tools now return an absolute path in their success message. Copy that path. If you still want to control the folder, set `LOCALAGENT_OUTPUT_DIR` (see above).

---

## What’s inside

- `agent.py` – creates the agent and wires up tools
- `retriever.py` – embeddings + ChromaDB add/query
- `tools/` – wiki, duckduckgo, serp_search (SerpAPI), searx_search (SearxNG), arxiv, crossref, europe_pmc, openlibrary, unpaywall, math, date, asknews, save_md, save_md_plus, summarize_text
- `prompts/research_prompt.py` – the system prompt

That’s it. Keep it simple, keep it local, have fun.

LocalAgent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README