Skip to content

Commit c19be87

Browse files
bearlikebearlike
committed
🧹 chore(repo): update docs, CI coverage, and tests
1 parent 46611e0 commit c19be87

11 files changed

Lines changed: 210 additions & 97 deletions

File tree

‎.github/git-commit-instructions.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Git Commit + PR Instructions (Meeseeks)
2+
3+
Use this file for **every** commit and PR title/body in this repo. It codifies our Gitmoji + Conventional Commits rules and common pitfalls to avoid.
4+
5+
## Required format (Gitmoji + Conventional Commits)
6+
```
7+
<gitmoji> <type>(<scope>): <description>
8+
9+
<body>
10+
11+
<footer>
12+
```
13+
14+
### Type (Conventional Commits)
15+
Use one of: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
16+
`build`, `ci`, `chore`, `revert`.
17+
18+
### Scope (required here)
19+
Use a **real module/component** name. Examples:
20+
`orchestration`, `core`, `tools`, `mcp`, `permissions`, `cli`, `api`, `chat`,
21+
`ha`, `prompts`, `docs`, `ci`, `build`, `tests`.
22+
23+
Avoid random scopes (e.g. `release`, `misc`, `tmp`).
24+
25+
### Description
26+
Imperative, short, and specific (e.g., "stabilize MCP tool inputs").
27+
28+
### Breaking changes
29+
Use `!` after the type/scope and include a `BREAKING CHANGE:` footer entry.
30+
31+
## Gitmoji mapping (use the right one)
32+
- ✨ feat: new feature
33+
- 🐛 fix: bug fix
34+
- ⚡️ perf: performance improvement
35+
- ♻️ refactor: refactor without behavior change
36+
- 🧪 test: tests only
37+
- 📝 docs: documentation
38+
- 👷 ci: CI changes
39+
- 🏗️ build: build system/deps
40+
- 🔧 chore: misc non-src/non-test changes
41+
- ⏪️ revert: revert
42+
- 💄 style: formatting only
43+
44+
Use unicode emoji (not `:shortcode:`) for commit titles.
45+
46+
Avoid overusing ✨. Use it **only** for new user-facing features.
47+
48+
## Example titles (use this exact format)
49+
- 🧪 chore(ci): avoid openai in orchestration test
50+
- 🐛 fix(orchestration): stabilize MCP tool inputs
51+
- 📝 docs(readme): refresh badges and setup links
52+
53+
## Commit body (required)
54+
Always include a body with:
55+
1. **What changed** (bulleted list).
56+
2. **Why** (brief rationale).
57+
3. **Tests run** (or "Not run" + reason).
58+
4. **Dependencies / env changes** (if any).
59+
60+
Example body:
61+
```
62+
- Add schema-aware MCP input coercion and update tool manifest.
63+
- Fix tool response synthesis step to keep user-facing output clean.
64+
65+
Tests: poetry run pytest tests/test_orchestration.py -q
66+
```
67+
68+
## PR titles and bodies
69+
PR titles must use the same `<gitmoji> <type>(scope): description` format.
70+
PR bodies must list:
71+
- Summary of changes
72+
- Tests run
73+
- Notes/risks (if any)
74+
75+
## Common pitfalls (avoid)
76+
- Wrong Gitmoji (e.g., using ✨ for docs/ci/refactor).
77+
- Missing/incorrect scope.
78+
- Empty body or no tests listed.
79+
- Overly broad or vague description.

‎.github/workflows/coverage.yml‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Pytest Coverage
1+
name: Test Coverage
22

33
on:
44
push:
@@ -48,16 +48,37 @@ jobs:
4848
--cov-report=xml \
4949
--cov-report=term-missing:skip-covered
5050
51+
- name: Generate core-only coverage report
52+
run: |
53+
if ls .coverage.* 1>/dev/null 2>&1; then
54+
poetry run coverage combine
55+
fi
56+
poetry run coverage xml \
57+
--data-file .coverage \
58+
--include "*core/*" \
59+
-o coverage-core.xml
60+
5161
- name: Upload coverage artifact
5262
uses: actions/upload-artifact@v4
5363
with:
5464
name: coverage-xml
55-
path: coverage.xml
65+
path: |
66+
coverage.xml
67+
coverage-core.xml
5668
57-
- name: Upload to Codecov
69+
- name: Upload overall coverage to Codecov
5870
uses: codecov/codecov-action@v5
5971
with:
6072
files: ./coverage.xml
61-
flags: unit
73+
token: ${{ secrets.CODECOV_TOKEN }}
74+
fail_ci_if_error: false
75+
use_oidc: true
76+
77+
- name: Upload core coverage to Codecov
78+
uses: codecov/codecov-action@v5
79+
with:
80+
files: ./coverage-core.xml
81+
flags: core
82+
token: ${{ secrets.CODECOV_TOKEN }}
6283
fail_ci_if_error: false
6384
use_oidc: true

‎.github/workflows/docker-buildx.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
# * The 'latest' and 'stable' tags allow us to easily switch between different versions.
1717
# * The 'dev' tag allows you to have a separate version for development.
1818

19-
name: Build and Push Docker Images
19+
name: Docker Images
2020

2121
on:
2222
workflow_dispatch:

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: docs
1+
name: Docs Build
22

33
on:
44
push:

‎.github/workflows/lint.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Lint
1+
name: Lint Checks
22

33
on:
44
push:

‎README.md‎

Lines changed: 17 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,15 @@
22
<h1 align="center">Meeseeks: The Personal Assistant 👋</h1>
33

44
<p align="center">
5-
<a href="https://github.com/bearlike/Personal-Assistant/wiki"><img alt="Wiki" src="https://img.shields.io/badge/GitHub-Wiki-blue?style=for-the-badge&logo=github"></a>
6-
<a href="https://github.com/features/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/bearlike/Personal-Assistant/docker-buildx.yml?style=for-the-badge&"></a>
7-
<a href="https://github.com/bearlike/Personal-Assistant/releases"><img src="https://img.shields.io/github/v/release/bearlike/Personal-Assistant?style=for-the-badge&" alt="GitHub Release"></a>
8-
<a href="https://github.com/bearlike/Personal-Assistant/pkgs/container/meeseeks-chat"><img src="https://img.shields.io/badge/ghcr.io-bearlike/meeseeks--chat:latest-blue?style=for-the-badge&logo=docker&logoColor=white" alt="Docker Image"></a>
9-
<a href="https://github.com/bearlike/Personal-Assistant/pkgs/container/meeseeks-api"><img src="https://img.shields.io/badge/ghcr.io-bearlike/meeseeks--api:latest-blue?style=for-the-badge&logo=docker&logoColor=white" alt="Docker Image"></a>
5+
<a href="https://deepwiki.com/bearlike/Personal-Assistant"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg"></a>
6+
<a href="https://github.com/bearlike/Personal-Assistant/actions/workflows/docker-buildx.yml"><img alt="Build and Push Docker Images" src="https://github.com/bearlike/Personal-Assistant/actions/workflows/docker-buildx.yml/badge.svg"></a>
7+
<a href="https://codecov.io/gh/bearlike/Personal-Assistant"><img alt="Coverage" src="https://codecov.io/gh/bearlike/Personal-Assistant/branch/main/graph/badge.svg"></a>
8+
<a href="https://codecov.io/gh/bearlike/Personal-Assistant?flags=core"><img alt="Coverage (core)" src="https://codecov.io/gh/bearlike/Personal-Assistant/branch/main/graph/badge.svg?flags=core"></a>
9+
<a href="https://github.com/bearlike/Personal-Assistant/actions/workflows/lint.yml"><img alt="Lint" src="https://github.com/bearlike/Personal-Assistant/actions/workflows/lint.yml/badge.svg"></a>
10+
<a href="https://github.com/bearlike/Personal-Assistant/actions/workflows/docs.yml"><img alt="Docs" src="https://github.com/bearlike/Personal-Assistant/actions/workflows/docs.yml/badge.svg"></a>
11+
<a href="https://github.com/bearlike/Personal-Assistant/releases"><img src="https://img.shields.io/github/v/release/bearlike/Personal-Assistant" alt="GitHub Release"></a>
12+
<a href="https://github.com/bearlike/Personal-Assistant/pkgs/container/meeseeks-chat"><img src="https://img.shields.io/badge/ghcr.io-bearlike/meeseeks--chat:latest-blue?logo=docker&logoColor=white" alt="Docker Image"></a>
13+
<a href="https://github.com/bearlike/Personal-Assistant/pkgs/container/meeseeks-api"><img src="https://img.shields.io/badge/ghcr.io-bearlike/meeseeks--api:latest-blue?logo=docker&logoColor=white" alt="Docker Image"></a>
1014
</p>
1115

1216

@@ -19,7 +23,7 @@
1923
</p>
2024

2125
# Project Motivation 🚀
22-
Meeseeks is a personal assistant built on an LLM-driven orchestration loop. It breaks a request into atomic steps, runs tools, and returns a clean summary. The core loop can replan after tool failures and keep short-term state while sessions persist on disk for continuity.
26+
Meeseeks is a personal assistant built on an LLM-driven orchestration loop. It breaks a request into atomic steps, runs tools, and returns a synthesized response. The core loop can replan after tool failures and keeps short-term state while sessions persist on disk.
2327

2428

2529
<details>
@@ -32,8 +36,6 @@ Meeseeks is a personal assistant built on an LLM-driven orchestration loop. It b
3236
</details>
3337

3438
# Features 🔥
35-
> [!NOTE]
36-
> Visit [**Features - Wiki**](https://github.com/bearlike/Personal-Assistant/wiki/Features) for detailed information on tools and integration capabilities.
3739

3840
<table align="center">
3941
<tr>
@@ -56,8 +58,9 @@ Meeseeks is a personal assistant built on an LLM-driven orchestration loop. It b
5658
- (✅) MCP tool visibility and model switch wizard in the CLI.
5759
- (✅) Plan -> act -> observe loop with re-planning on tool failures.
5860
- (✅) Session transcripts with lightweight compaction for long-running chats.
59-
- (✅) Tool registry with optional MCP tool support via manifest.
61+
- (✅) Tool registry with MCP auto-discovery and optional manifest override.
6062
- (✅) Permission gate + hooks around tool execution for safer runs.
63+
- (✅) Tool response synthesis before user-facing replies.
6164

6265
## Extras 👽
6366
Optional feature that users can choose to install to further optimize their experience.
@@ -97,24 +100,11 @@ flowchart LR
97100
Core --> SessionStore
98101
```
99102

100-
## Installing and Running Meeseeks
101-
> [!IMPORTANT]
102-
> For Docker or manual installation, running, and configuring Meeseeks, visit [**Installation - Wiki**](https://github.com/bearlike/Personal-Assistant/wiki/Installation) or read `docs/index.md` for a quick local/deploy overview.
103-
104-
## MCP servers (quick setup)
105-
MCP tools are auto-discovered from your MCP server config.
106-
- Copy `configs/mcp.example.json` and set the MCP server URL + headers.
107-
- Set `MESEEKS_MCP_CONFIG` in `.env`.
108-
- First run will auto-generate the tool manifest under `~/.meeseeks/` and refresh it on each load.
109-
- Optional: add `auto_approve_tools` under each server to allowlist tools (the CLI writes this when you pick “Yes, always”).
110-
111-
Advanced: set `MESEEKS_TOOL_MANIFEST` to override the tool list (disables auto-discovery).
112-
Tip: if you override the manifest, include `talk_to_user_tool` so the assistant can still reply.
113-
114-
## Optional components
115-
- **Langfuse** is optional. Enable it by setting `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` (or disable with `LANGFUSE_ENABLED=0`).
116-
- **Home Assistant** tools are optional. Enable them by setting `HA_URL` and `HA_TOKEN` (or disable with `MESEEKS_HOME_ASSISTANT_ENABLED=0`).
117-
- Optional components auto-disable when init/runtime/auth fails, with logs explaining the reason.
103+
## Documentation
104+
- [docs/index.md](docs/index.md) - product overview and architecture
105+
- [docs/getting-started.md](docs/getting-started.md) - setup guide (env, MCP, configs, run paths)
106+
- [docs/components.md](docs/components.md) - monorepo map
107+
- [docs/reference.md](docs/reference.md) - API reference (mkdocstrings)
118108

119109
---
120110

‎agents.md‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,22 @@
1-
# Agents Guide — Personal Assistant (Meeseeks)
1+
# Agents Guide - Personal Assistant (Meeseeks)
22

33
## What this codebase is
4-
Meeseeks is a multi‑agent LLM personal assistant that decomposes user requests into atomic actions, runs them through tools, and returns a summarized response. It ships three interfaces (Streamlit chat UI, Flask REST API, Home Assistant integration) that all call the same core engine.
4+
Meeseeks is a multi-agent LLM personal assistant that decomposes user requests into atomic actions, runs them through tools, and returns a synthesized response. It ships multiple interfaces (CLI, chat UI, REST API, Home Assistant) that share the same core engine.
55

66
## Core entry points
77
- `core/task_master.py`: action planning + task execution loop
88
- `core/classes.py`: `ActionStep`, `TaskQueue`, `AbstractTool` contracts
99
- `tools/`: tool implementations and integration glue
1010
- `meeseeks-chat/chat_master.py`: Streamlit UI
1111
- `meeseeks-api/backend.py`: Flask API
12+
- `meeseeks-cli/cli_master.py`: terminal CLI
1213
- `meeseeks_ha_conversation/`: Home Assistant integration
1314

1415
## How to get context fast
15-
1. Use the DeepWiki MCP tool on `bearlike/Personal-Assistant` for a high‑level map of architecture, flows, and interfaces.
16-
2. Read `README.md` and component READMEs for configuration and runtime details.
17-
3. Use `rg` to locate specific behavior (`ActionPlanner`, `TaskMaster`, `tool_dict`, API routes, HA service calls).
18-
4. Open the exact files you need; keep context small and focused.
16+
1. Use the DeepWiki MCP tool on `bearlike/Personal-Assistant` for a fast architecture map.
17+
2. Read `README.md` and component READMEs for configuration/runtime details.
18+
3. Use `rg` to locate specific behavior and follow the exact file path.
19+
4. For CI issues, use GitHub Actions logs (GH CLI or MCP GitHub tools).
1920

2021
## MCP tools (use first for external research)
2122
When you need external context (other repos, CI failures, specs, APIs), prefer MCP tools instead of guessing.
@@ -26,14 +27,27 @@ When you need external context (other repos, CI failures, specs, APIs), prefer M
2627
- Context7 Docs: official library/framework docs and code examples.
2728
- Notifications: send status updates to the human owner when needed.
2829

29-
## Engineering principles (project‑specific)
30+
## Engineering principles (project-specific)
3031
- KISS and DRY: prefer small, obvious changes; remove redundancy instead of adding layers.
3132
- KRY: keep requirements and acceptance criteria in view; do not drift.
3233
- Keep tool contracts stable (`AbstractTool`, `ActionStep`, `TaskQueue`).
3334
- Favor composition and reuse across interfaces; avoid duplicating core logic.
34-
- Add or improve tests for non‑trivial behavior; expand coverage when touching core logic or tools.
35-
- Use Gitmoji + Conventional Commit format (e.g., `✨ feat: add session summary pass-through`).
36-
- Do not push unless explicitly requested.
35+
- Add or improve tests for non-trivial behavior; expand coverage when touching core logic or tools.
36+
- Use Gitmoji + Conventional Commit format (e.g., `✨ feat: add session summary pass-through`).
37+
- Do not push unless explicitly requested.
38+
- Use `.github/git-commit-instructions.md` for commit + PR titles and bodies.
39+
40+
## Orchestration insights (transferable)
41+
- Separate tool execution from user-facing response: synthesize after tool results, don't dump raw tool output.
42+
- Keep the loop explicit: plan -> act -> observe -> decide; re-plan only when needed.
43+
- Make tool inputs schema-aware; prefer structured arguments for MCP tools.
44+
- Surface tool activity clearly (permissions, tool IDs, arguments) to reduce user confusion.
45+
46+
## Testing patterns (what worked)
47+
- Mock as little as possible; prefer real code paths with stubbed I/O boundaries.
48+
- Cover the full orchestration loop with fake tools and fake LLM outputs.
49+
- Ensure tests fail when tool args are malformed (schema + coercion paths).
50+
- Avoid hidden defaults in tests that mask production behavior.
3751

3852
## Testing & running (common paths)
3953
- Tests live under `tests/` (use `pytest`).

‎docs/getting-started.md‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,57 @@
11
# Getting Started
22

3-
## Prerequisites
3+
This guide walks through local setup, environment configuration, MCP setup, and how to run each interface.
44

5+
## Prerequisites
56
- Python 3.11+
6-
- Poetry (or pip + a virtual environment)
7-
8-
## Install documentation dependencies
7+
- Poetry
8+
- Docker (optional, for container runs)
99

10+
## Install dependencies
1011
```bash
11-
pip install -r requirements-docs.txt
12+
poetry install
1213
```
1314

14-
## Run the docs locally
15-
15+
## Environment setup
16+
1. Copy `.env.example` to `.env`.
17+
2. Set at least:
18+
- `OPENAI_API_KEY` (or your compatible provider key)
19+
- `OPENAI_API_BASE` (if you are using a local or custom API base)
20+
- `DEFAULT_MODEL` (or `ACTION_PLAN_MODEL`)
21+
3. Optional runtime paths:
22+
- `MESEEKS_SESSION_DIR` for session transcript storage
23+
- `MESEEKS_TOOL_MANIFEST` if you want a custom tool list (disables MCP auto-discovery)
24+
25+
## MCP setup (auto-discovery)
26+
MCP tools are auto-discovered from a server config file.
27+
1. Copy `configs/mcp.example.json` to `configs/mcp.json`.
28+
2. Set the MCP server `url` and any `headers` needed for auth.
29+
3. Set `MESEEKS_MCP_CONFIG=./configs/mcp.json` in `.env`.
30+
4. Start any interface once; a tool manifest is auto-generated and cached under `~/.meeseeks/`.
31+
32+
Notes:
33+
- If you override the manifest, include `talk_to_user_tool` so the assistant can still reply.
34+
- MCP tool names must match the server's advertised tool list.
35+
36+
## Optional components
37+
- Langfuse: set `LANGFUSE_PUBLIC_KEY` + `LANGFUSE_SECRET_KEY` (or disable with `LANGFUSE_ENABLED=0`).
38+
- Home Assistant: set `HA_URL` + `HA_TOKEN` (or disable with `MESEEKS_HOME_ASSISTANT_ENABLED=0`).
39+
40+
## Run interfaces (local)
41+
- API: `python meeseeks-api/backend.py`
42+
- Chat UI: `streamlit run meeseeks-chat/chat_master.py`
43+
- CLI: `python meeseeks-cli/cli_master.py`
44+
- Home Assistant integration: install `meeseeks_ha_conversation/` as a custom component and point it at the API.
45+
46+
## Docker (optional)
47+
- Build images using the provided Dockerfiles for API/chat.
48+
- Provide the same `.env` values as local.
49+
- Persist `MESEEKS_SESSION_DIR` if you want transcripts across restarts.
50+
51+
## Docs (optional)
52+
If you want to build the docs locally:
1653
```bash
54+
pip install -r requirements-docs.txt
1755
export PYTHONPATH="$PWD"
1856
mkdocs serve
1957
```
20-
21-
The documentation will be available at http://127.0.0.1:8000/.
22-
23-
## Build the docs
24-
25-
```bash
26-
export PYTHONPATH="$PWD"
27-
mkdocs build
28-
```

0 commit comments

Comments
 (0)