Metadata-Version: 2.4
Name: ageri-sdk
Version: 0.5.0
Summary: Skill contract for the Ageri personal-AI platform — SkillBase, SkillResult, Task, OrchestratorContext, and proxy ABCs.
Author-email: Huy Do <ageri.platform@gmail.com>
License: MIT
Project-URL: Homepage, https://ageri.ai
Project-URL: Documentation, https://docs.ageri.ai/sdk/
Project-URL: Repository, https://github.com/ageri-platform/ageri-sdk
Project-URL: Issues, https://github.com/ageri-platform/ageri-sdk/issues
Project-URL: Changelog, https://github.com/ageri-platform/ageri-sdk/blob/main/CHANGELOG.md
Keywords: ageri,ai,agent,skill,llm,automation,chief-of-staff
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# ageri-sdk

Skill contract for the [Ageri](https://ageri.ai) personal-AI platform.

Ageri is a self-hosted "chief of staff" agent system that runs 24/7, remembers
across sessions, and coordinates specialist **skills** across every domain of
your work. This package is the **stable boundary** every skill imports from —
the abstract base classes, dataclasses, and helpers that define what a skill
looks like to the Ageri runtime.

If you want to **author** an Ageri skill, install this package. If you want to
**run** Ageri itself, see [docs.ageri.ai/install](https://docs.ageri.ai/install).

---

## Install

```bash
pip install ageri-sdk
```

Python 3.11+ required. No runtime dependencies — the SDK is pure ABCs +
dataclasses. Skills declare their own deps in their bundle's `requirements.txt`.

## Minimal skill

```python
from ageri_sdk import SkillBase, SkillResult, Task, OrchestratorContext


class HelloSkill(SkillBase):
    name = "Hello"
    description = "Greets the user."
    version = "0.1.0"
    intent_domain = "general"

    async def handle(self, task: Task, ctx: OrchestratorContext) -> SkillResult:
        return SkillResult(
            status="done",
            response=f"Hello, {ctx.user.display_name}!",
        )
```

That's the whole contract. The runtime injects an `OrchestratorContext` with
proxies for memory, agents (LLMs), reply, browser/screen/input automation,
and so on. Your `handle()` does the work and returns a `SkillResult`.

## What's in the package

- **`SkillBase`** — abstract base every skill subclasses.
- **`Task`** — what the user asked for + routing metadata.
- **`SkillResult`** — what the skill produced (response + declared memory writes).
- **`OrchestratorContext`** — the only interface skills have to the outside
  world. Memory, agents, reply, user, agent identity, tools.
- **Proxy ABCs** — `MemoryProxy`, `AgentProxy`, `ReplyProxy`, `BrowserProxy`,
  `ScreenProxy`, `InputProxy`, `FsProxy`, `NetworkProxy`, `ClipboardProxy`,
  `ProcessProxy`. Skills code against these; the runtime supplies concrete
  implementations.
- **Helpers** — `SkillCommand` (slash-command metadata), `ConfigField`
  (declarable config schema), `MessagingSkillBase` (Slack/Telegram/Zalo-OA
  adapter base), vision-click + browser-automation primitives, and more.

Full API reference: <https://docs.ageri.ai/sdk/>.

## Versioning

`ageri-sdk` follows semver. The major version bumps if the contract breaks
(adding a required method to `SkillBase`, changing a dataclass field that
already-shipped skills rely on, etc.). Minor versions add new capabilities;
patch versions are bugfixes.

Skill bundles declare their compatible SDK range via `manifest_compat` in
`skill.json`:

```json
{
  "manifest_compat": ">=0.5.0,<1.0.0"
}
```

The Ageri runtime refuses to load a skill whose `manifest_compat` doesn't
include the running SDK version.

## License

MIT. See [LICENSE](LICENSE).

The Ageri platform that consumes this SDK has its own license (see the main
[Ageri repo](https://github.com/ageri-platform/ageri)). The SDK is MIT so
skill authors can freely build on it, publish skills under whatever license
they choose, and integrate against Ageri without IP friction.
