Chanakya-Local-Friend

# Chanakya Chanakya is an **advanced, open-source, and self-hostable voice assistant** designed for privacy, power, and flexibility. It can leverage local AI/ML models to help keep data under your control and supports connecting to third-party MCP servers through configuration. A network of intelligent agents collaborates to complete tasks, provide insights, and maintain ongoing workflows. - Chanakya Flask app on `http://127.0.0.1:5513` - AIR service on `http://127.0.0.1:5512` - Conversation layer on `http://127.0.0.1:5514` - Optional A2A bridge on `http://127.0.0.1:18770` The most important setup rule is simple: create the repo-root `.env` and `mcp_config_file.json` before starting the stack. The startup scripts read those files immediately. ## Quick Start ### 1. Prerequisites - Python 3.11 is the safest default for local development. - `python3.11 -m venv` available on your machine. - `uvx` available if you use the example MCP config as-is. - An OpenAI-compatible API key and base URL. ### 2. Create the virtual environment From the repo root: ```bash python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e .[dev] python -m pip install -e ./apps/AI-Router-AIR python -m pip install -e ./apps/chanakya_conversation_layer ``` If you prefer conda for day-to-day development, that is still fine. The only hard requirement is that the `systemd` installer expects a repo-root `.venv`. ### 3. Create `.env` before starting anything Start from the checked-in template: ```bash cp .env.example .env ``` Then edit `.env` for your machine and credentials. Use `.env.example` as the source of truth for supported variables. The startup scripts source this file automatically and export `ENV_FILE_PATH` for child processes. If this file is missing, the services start without your intended runtime configuration. ### 4. Create `mcp_config_file.json` before starting anything The app expects a repo-root `mcp_config_file.json`. Start from the example: ```bash cp mcp_config_file.example.json mcp_config_file.json ``` Then edit it for your environment if needed. Use `mcp_config_file.example.json` as the source of truth for the default MCP server layout. The checked-in example includes both local Python-backed MCP servers and `uvx`-launched servers. ### 5. Start the stack Core stack: ```bash ./scripts/start_chanakya_air.sh core ``` Core stack plus A2A components: ```bash ./scripts/start_chanakya_air.sh core+a2a ``` Open the main UI at `http://127.0.0.1:5513`. ### 6. Stop the stack ```bash ./scripts/stop_chanakya_air.sh ``` ## What The Startup Script Does `./scripts/start_chanakya_air.sh` starts the current local stack in this order: 1. AIR service 2. Chanakya conversation layer 3. Optional A2A services for `core+a2a` 4. Chanakya Flask app It also: - reads `.env` from the repo root unless `ENV_FILE_PATH` is already set - writes PID files and logs under `build/runtime/` - prints the service URLs after startup Use `./scripts/stop_chanakya_air.sh` to stop everything cleanly. ## Required Configuration ### `.env` Start from `.env.example` and copy it into place: ```bash cp .env.example .env ``` Then edit `.env` with your local values. Replace all placeholder values marked with `<...>`: | Variable | Description | Example | |----------|-------------|---------| | `OPENAI_BASE_URL` | Your LM Studio or OpenAI-compatible server endpoint | `http://127.0.0.1:1234/v1` | | `OPENAI_API_KEY` | API key for your model server | `lm-studio` (or your key) | | `DATABASE_URL` | Path to your SQLite database | `sqlite:////home/user/chanakya_data/chanakya.db` | The defaults in `.env.example` use placeholder values and will not work out of the box. Common variables used in local development include: ```bash CHANAKYA_CORE_AGENT_BACKEND=local A2A_AGENT_URL=http://127.0.0.1:18770 AIR_SERVER_PORT=5512 CHANAKYA_PORT=5513 CONVERSATION_LAYER_PORT=5514 ``` ### `mcp_config_file.json` Start from the checked-in template: ```bash cp mcp_config_file.example.json mcp_config_file.json ``` This file defines the MCP servers Chanakya can connect to. The example file already includes entries for: - `mcp_websearch` - `mcp_fetch` - `mcp_calculator` - `mcp_code_execution` - `mcp_filesystem` - `mcp_git` - `mcp_http` - `mcp_json` - `mcp_shell_utils` - `mcp_weather` - `mcp_map` - `mcp_timer` - `mcp_work_tools` - `mcp_artifact_tools` If you add or remove MCP servers, restart the stack afterward so the tool loader reconnects using the updated config. ## Local Development ### Test, lint, and type-check From the repo root with the environment activated: ```bash pytest apps/chanakya/test python -m ruff check apps/chanakya/ python -m mypy apps/chanakya/ ``` For a focused test run: ```bash pytest apps/chanakya/test/test_agent_manager.py -q ``` ### Database utilities ```bash python scripts/db_viewer.py python scripts/update_database.py python scripts/clear_database.py ``` Notes: - `scripts/clear_database.py` is destructive. - If `DATABASE_URL` is unset, the default SQLite database is `chanakya_data/chanakya.db`. ### Manual smoke checks These rely on external tooling and are not the default verification path: ```bash python scripts/run_maf_tools.py python scripts/test_mcp_fetch_connectivity.py --mode with-wrapper python scripts/test_mcp_fetch_connectivity.py --mode without-wrapper ``` ## Runtime Files Runtime state is written under `chanakya_data/` and `build/runtime/`. - `chanakya_data/` holds application state such as the SQLite database and shared workspace data. - `build/runtime/` holds PID files and service logs from the startup scripts. If something fails to boot, check the recent logs in `build/runtime/` first. ## Service Installation On Ubuntu The repo includes a `systemd` installer for the core stack: ```bash sudo ./scripts/install-autostart-ubuntu.sh ``` Important details: - it requires a repo-root `.venv` - it passes `ENV_FILE_PATH` pointing at the repo-root `.env` - it installs services for the invoking non-root user by default Useful commands: ```bash sudo systemctl status chanakya.target sudo journalctl -u chanakya-air.service -f sudo journalctl -u chanakya-conversation-layer.service -f sudo journalctl -u chanakya-app.service -f sudo systemctl restart chanakya.target ``` Uninstall: ```bash sudo ./scripts/uninstall-autostart-ubuntu.sh ``` ## Repository Layout This workspace contains a few related codebases. The main ones are: - `apps/chanakya/`: primary Flask app, routes, templates, core state, tests - `apps/AI-Router-AIR/`: FastAPI service used by the local stack on port 5512 - `apps/chanakya_conversation_layer/`: separate conversation-layer package and tests - `scripts/`: startup, shutdown, database, and service-management scripts If you are changing runtime behavior, the most relevant files are usually: - `apps/chanakya/core/app.py` - `apps/chanakya/core/chat_service.py` - `apps/chanakya/core/store.py` - `apps/chanakya/agent/runtime.py` - `apps/chanakya/templates/` - `apps/chanakya/static/js/air_voice.js` ## Common Problems ### The stack starts but behaves incorrectly Check these first: 1. `.env` exists at the repo root and has the expected model credentials. 2. `mcp_config_file.json` exists at the repo root. 3. The virtual environment includes all three editable installs. 4. `build/runtime/*.log` shows all services stayed up after startup. ### A service starts with the wrong environment The startup scripts source the repo-root `.env` automatically. If you want a different env file, set `ENV_FILE_PATH` before invoking the script. ### MCP tools are missing Confirm that: 1. the tool exists in `mcp_config_file.json` 2. its command is installed on your machine 3. you restarted the stack after editing the MCP config ## Related Files - `mcp_config_file.example.json`: starting point for MCP server configuration - `scripts/start_chanakya_air.sh`: standard local stack entrypoint - `scripts/stop_chanakya_air.sh`: standard shutdown entrypoint - `scripts/install-autostart-ubuntu.sh`: `systemd` installer for Linux