diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..9769b18 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,17 @@ +--- +name: Bug report +about: A sample doesn't run as documented +labels: bug +--- + +**Which sample** (e.g. `langchain/`, `nextjs/`, `typescript/mastra/`) + +**What happened** + +**Steps to reproduce** + +**Expected** + +**Environment** (framework version, runtime/OS, `kak_test_` or `kak_live_`) + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6dcbdee --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Security vulnerability + url: https://github.com/nqzai/kakunin-core/security/policy + about: Report privately per SECURITY.md — never a public issue. + - name: Docs & support + url: https://www.kakunin.ai/docs + about: Product docs and API reference. diff --git a/.github/ISSUE_TEMPLATE/new_framework_sample.md b/.github/ISSUE_TEMPLATE/new_framework_sample.md new file mode 100644 index 0000000..ec525fa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new_framework_sample.md @@ -0,0 +1,15 @@ +--- +name: New framework sample +about: Propose (or claim) a sample for a framework we don't cover yet +labels: enhancement, good first issue +--- + +**Framework** (name + link to its docs/repo) + +**Language** (Python / TypeScript / other) + +**Are you offering to write it?** (yes — assign me / no — just requesting) + +**Notes** + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..7552675 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ +## What this changes + + + +## Why + + + +## Checklist + +- [ ] Scoped to one thing — small, focused PRs get reviewed fastest +- [ ] Tests / examples updated (or N/A with a reason) +- [ ] `README` / docs updated if behavior or setup changed +- [ ] CI is green (build, tests, type-check) +- [ ] I signed the CLA on my first PR (the bot comments a one-click link) + + diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000..189a079 --- /dev/null +++ b/.mailmap @@ -0,0 +1,4 @@ +# Canonical identities. Collapses multiple git author strings for the same +# person so `git shortlog -sne` and GitHub contributor counts are truthful. +Palash Bagchi nqzai +Palash Bagchi nqzai diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e6d755c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,92 @@ +# Contributing to Kakunin samples + +Thanks for helping other developers integrate Kakunin. This repo is the **lowest-friction +way to contribute** — every sample runs against the hosted API with a single test key, so +you don't need to provision any infrastructure. + +## Ground rules + +- **Solo-maintainer project (for now).** Best-effort support; triage target is one week. + Small, focused PRs get reviewed fastest. +- **Security issues:** never open a public issue — see the platform's + [SECURITY.md](https://github.com/nqzai/kakunin-core/blob/main/SECURITY.md). +- Contributions are licensed under **MIT** (this repo's license). A lightweight CLA check + runs on your first PR — one click to sign. + +## Ways to contribute + +| Effort | What | Where | +|---|---|---| +| **Small** | Fix a typo, broken link, or stale version in a sample README | any `*/README.md` | +| **Small** | Fix a sample that no longer runs against the current SDK | the affected dir | +| **Medium** | **Add a sample for a framework we don't cover yet** ← highest-value | new top-level dir | +| **Medium** | Improve an existing sample (error handling, comments, a second scenario) | the affected dir | + +### Frameworks we'd love a sample for + +No sample exists for these yet — each is a self-contained new directory, mergeable in an +afternoon: + +- **Pydantic AI** — https://ai.pydantic.dev +- **Semantic Kernel** — https://github.com/microsoft/semantic-kernel +- **Agno** (formerly Phidata) — https://github.com/agno-agi/agno +- **Smolagents** (Hugging Face) — https://github.com/huggingface/smolagents +- **Letta** (formerly MemGPT) — https://github.com/letta-ai/letta +- **Google ADK** (Agent Development Kit) — https://google.github.io/adk-docs +- **DSPy** — https://github.com/stanfordnlp/dspy +- **Strands** (AWS) — https://github.com/strands-agents/sdk-python +- **LangGraph** — https://github.com/langchain-ai/langgraph + +Using a framework not on this list? A sample for it is still welcome — open a +[new-framework-sample issue](../../issues/new?template=new_framework_sample.md) first so we +can coordinate. + +## Get set up + +```bash +# Open in the devcontainer (recommended) or locally. +# Get a free sandbox key at https://kakunin.ai/dashboard/api-keys +export KAKUNIN_API_KEY=kak_test_... +``` + +A `kak_test_...` key hits the sandbox CA — no cost, no real certificates. + +## Add a framework sample — the 20-minute skeleton + +Copy the closest existing sample (e.g. [`langchain/`](./langchain/) for Python, +[`typescript/`](./typescript/) for TS) and adapt it. Every sample follows the same shape: + +``` +/ +├── README.md # What it demonstrates, prerequisites, setup, run, "how it works" +├── register_agent.py # (or .ts) — register + certify an agent once, print the agent ID +├── quickstart.py # (or .ts) — the actual integration: gate a tool/action on the cert +└── requirements.txt # (or package.json) — pinned deps +``` + +The integration itself is small — verify the agent's certificate and scope **before** the +framework executes a tool or action: + +```python +from kakunin import Kakunin + +kkn = Kakunin(api_key=os.environ["KAKUNIN_API_KEY"]) + +# Before your framework runs a tool: +decision = await kkn.verify_agent_scope(agent_id=AGENT_ID, required_scopes=["market_data:read"]) +if not decision.allowed: + raise PermissionError(decision.reason) # cert inactive or scope missing +``` + +Match the README structure of an existing sample so the set stays consistent. Add your +sample to the table in the [root README](./README.md), and cross-link it under "Related" in +one or two neighboring samples. + +## Pull requests + +1. For a new framework sample, open the issue first so we don't duplicate work. +2. Keep the PR to one sample / one fix. +3. Make sure the sample actually runs against a real `kak_test_` key before you open the PR. +4. CI must be green. + +We review fast and we credit every contributor. Welcome aboard.