Metadata-Version: 2.4
Name: concinno-skills-knowledge
Version: 0.1.0
Summary: Knowledge-base agent skills (Notion/Confluence/Obsidian) for Concinno — native Python API. MIT / Apache-2.0 / BSD SDKs only.
Project-URL: Homepage, https://github.com/aiking931931/concinno
Project-URL: Issues, https://github.com/aiking931931/concinno/issues
Project-URL: Changelog, https://github.com/aiking931931/concinno/blob/main/projects/concinno-skills-knowledge/CHANGELOG.md
Author-email: "AI King (Chen-Xuan Wang)" <me@ai-king.dev>
License-Expression: Apache-2.0
Keywords: agent,concinno,confluence,knowledge,notes,notion,obsidian,skills,wiki
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: atlassian-python-api>=3.41
Requires-Dist: concinno>=2.15.1
Requires-Dist: notion-client>=2.2
Requires-Dist: python-frontmatter>=1.1
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# concinno-skills-knowledge

Knowledge-base agent skills for [Concinno](https://pypi.org/project/concinno/).
Native Python API, no MCP required. **MIT / Apache-2.0 / BSD licensed SDKs
only** — we deliberately keep the Concinno ecosystem permissive-licence-clean.

## Status

MVP (0.1.0) — five one-shot tools covering Notion, Confluence, and local
Obsidian vaults:

| Tool class           | Platform         | Underlying SDK              | SDK licence |
|----------------------|------------------|-----------------------------|-------------|
| `NotionPage`         | Notion           | `notion-client`             | MIT         |
| `NotionDatabase`     | Notion (DB)      | `notion-client`             | MIT         |
| `ConfluencePage`     | Atlassian Cloud  | `atlassian-python-api`      | Apache-2.0  |
| `ObsidianVault`      | Obsidian (local) | stdlib + `python-frontmatter` | MIT       |
| `ObsidianDailyNote`  | Obsidian (local) | stdlib + `python-frontmatter` | MIT       |

Dendron, Logseq, and Evernote are intentionally deferred until a
maintained Python SDK with a permissive licence exists. Atlassian
Server / Data Center is out of scope (Atlassian stopped selling it in
2024).

## Install

```bash
pip install concinno-skills-knowledge
```

All three SDK dependencies are hard requirements and pulled in
automatically. `python-frontmatter` is used by the Obsidian tools only;
it is <50kB so we do not gate it behind an optional extra.

## Credentials

All credentials live under well-known keys in the Concinno
`CredentialStore`, which reads (in order):

1. Process runtime overrides via `CredentialStore.set(...)`.
2. Env var `CONCINNO_CRED_<UPPER_KEY>`.
3. `~/.concinno/credentials.json`.

| Key                         | Env var                                       |
|-----------------------------|-----------------------------------------------|
| `notion_token`              | `CONCINNO_CRED_NOTION_TOKEN`                  |
| `confluence_url`            | `CONCINNO_CRED_CONFLUENCE_URL`                |
| `confluence_email`          | `CONCINNO_CRED_CONFLUENCE_EMAIL`              |
| `confluence_api_token`      | `CONCINNO_CRED_CONFLUENCE_API_TOKEN`          |
| `obsidian_vault_path`       | `CONCINNO_CRED_OBSIDIAN_VAULT_PATH`           |

Example `~/.concinno/credentials.json`:

```jsonc
{
  "notion_token": "ntn_...",
  "confluence_url": "https://mycompany.atlassian.net",
  "confluence_email": "me@mycompany.com",
  "confluence_api_token": "atl-...",
  "obsidian_vault_path": "C:\\Users\\me\\Vault"
}
```

Obsidian has no server, but the vault root path lives in the same
credential store for UX consistency — users configure everything in one
place. Notion expects an integration token from
`https://www.notion.so/profile/integrations`; Confluence expects an
Atlassian API token from
`https://id.atlassian.com/manage-profile/security/api-tokens`.

If any required credential is missing the tool returns
`{"error": "no <service> credentials — set via CredentialStore or env ..."}`
rather than crashing.

## Usage via Concinno `ToolRegistry`

When the consumer sets `CONCINNO_LOAD_PLUGINS=1`, the default registry
auto-mounts every knowledge tool:

```python
import os
os.environ["CONCINNO_LOAD_PLUGINS"] = "1"

from concinno.tools.registry import get_default_registry

reg = get_default_registry()
expected = {
    "NotionPage",
    "NotionDatabase",
    "ConfluencePage",
    "ObsidianVault",
    "ObsidianDailyNote",
}
assert expected <= set(reg.list_deferred())

page = reg.get("NotionPage")
page.call(action="search", query="agent", limit=20)
```

## Direct Python usage

```python
from concinno_skills_knowledge import (
    NotionPage,
    NotionDatabase,
    ConfluencePage,
    ObsidianVault,
    ObsidianDailyNote,
)

# Notion
NotionPage().call(action="search", query="roadmap", limit=10)
NotionPage().call(action="get", page_id="...")
NotionDatabase().call(
    action="query",
    database_id="...",
    filter={"property": "Status", "status": {"equals": "Done"}},
)

# Confluence
ConfluencePage().call(action="search", query="platform", limit=30)
ConfluencePage().call(
    action="create",
    space="DOCS",
    title="Agent design",
    body="<p>draft</p>",
)

# Obsidian (local)
ObsidianVault().call(action="search", query="reranker")
ObsidianVault().call(
    action="write",
    path="notes/today.md",
    content="hello",
    frontmatter={"tags": ["agent"]},
)
ObsidianDailyNote().call(action="append", text="- shipped 0.1.0")
ObsidianDailyNote().call(action="read")  # today's note
```

All tools return `{"ok": True, ...}` on success or `{"error": "..."}`
on failure — same shape as the other Concinno built-in tools. No
exceptions escape the `call()` surface.

## Safety

`ObsidianVault` and `ObsidianDailyNote` resolve every `path` argument
through `Path.is_relative_to(vault_root)` after a canonical resolve, so
`../` traversal or absolute paths escape the vault are rejected with
`{"error": "path escapes vault subtree: ..."}`. Absolute paths are also
rejected up-front.

`NotionPage.search` and `NotionDatabase.query` cap `limit` at 100 (the
Notion API's own maximum); `ConfluencePage.search` caps at 100 as well.
`ObsidianVault.search` defaults to 50 hits with a 500 hard cap and
returns `"truncated": true` when the limit is reached.

## Concurrency

All five tools set `is_concurrency_safe = False`. KB platforms either
have strict rate limits (Notion 3 req/s, Confluence tighter) or open a
session-per-call (Obsidian writes); the Concinno scheduler will honour
this automatically.

## License

Apache-2.0.
