Add a minimal reproducible end-to-end example for running the knowledge-space agent locally

[tisha-varma]

Summary

The project currently provides a hosted demo at chat.knowledge-space.org, which is very helpful for understanding the user-facing behavior of the system.

However, the repository itself does not yet include a minimal, reproducible end-to-end example that shows how a developer can run the knowledge-space agent locally and understand the core workflow directly from code.

Adding a simple example (Python script or Jupyter notebook) would significantly improve developer onboarding and make it easier for new contributors and GSoC students to understand how the hosted demo maps to the underlying implementation.

Proposed Scope

The example could demonstrate:

• Configuring the agent with minimal environment setup
• Running the agent on a sample neuroscience-related query
• Inspecting the output, including:
  • Search results returned by the KnowledgeSpace API
  • The final synthesized response produced by the agent
    The example would focus on clarity and reproducibility rather than performance or UI.

Expected Benefit

• Improves onboarding for new contributors
• Makes the agent workflow easier to understand and extend
• Complements the existing hosted demo by documenting how to run the system locally
• Helps GSoC students explore the codebase more efficiently

Proposed Implementation

examples/
├── README.md # Setup instructions
├── basic_demo.py # Minimal Python script
└── basic_demo.ipynb # (Optional) Interactive notebook

Example Script Preview

(Illustrative example; exact API usage may be adjusted based on current implementation.)

from agents import NeuroscienceAssistant

assistant = NeuroscienceAssistant()
response = assistant.handle_chat(
session_id="demo",
query="Find datasets about hippocampus neurons in mice"
)

print(response)

[sanchalitorpe-source]

Hi @tisha-varma,
This is a great idea! A minimal reproducible example will definitely help new contributors and GSoC students get started quickly.

A few suggestions:

• We could include a small sample local_knowledge.json so users can run the example without needing external data.
• Adding a short README.md with setup instructions (dependencies, env variables) will make it plug-and-play.
• It might also help to show how to inspect the intermediate retrieval results and final synthesized output to understand the agent’s reasoning workflow.

I’d be happy to help put together the example script and notebook if needed!

[tisha-varma]

Hi, thank you so much for the encouraging feedback!

Those suggestions make a lot of sense, especially including a small local_knowledge.json and a concise README to make the example fully plug-and-play. I also agree that showing intermediate retrieval results alongside the final synthesized response would really help users understand the agent’s workflow.

I’ll start putting together a minimal example script and README incorporating these points, and I’d really appreciate your feedback once I open the PR. Thanks again for offering to help!

[SandeepChauhan00]

Hi @tisha-varma and @sanchalitorpe-source,

Apologies, I missed the comment above where you mentioned you were starting this!

Since I have the agent running locally (and just merged PR #43 for the Python fix), I wanted to offer my help.

If you are already working on it, I would love to test your PR on Windows or write the README.md part to support your work. However, if you are busy with other tasks, I am happy to implement the full example as described above.

Let me know how I can best support!