Metadata-Version: 2.4
Name: ersan
Version: 0.5.0
Summary: Open-source AI agent for Microsoft 365.
Author-email: Ersan Bilik <ersanbilik@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,microsoft-365,privacy
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: pydantic-ai>=1.73
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: pyyaml>=6.0
Provides-Extra: repl
Requires-Dist: prompt-toolkit>=3.0.50; extra == 'repl'
Description-Content-Type: text/markdown

```
 ███████╗██████╗ ███████╗ █████╗ ███╗   ██╗
 ██╔════╝██╔══██╗██╔════╝██╔══██╗████╗  ██║
 █████╗  ██████╔╝███████╗███████║██╔██╗ ██║
 ██╔══╝  ██╔══██╗╚════██║██╔══██║██║╚██╗██║
 ███████╗██║  ██║███████║██║  ██║██║ ╚████║
 ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝
```
> **Your office. Your rules. Your AI. ...and you, amplified.**

Open-source AI agent for Microsoft 365. Apache 2.0. Runs on your laptop
against your own tenant. No data leaves unless you tell it to.

---

## Why ersan

If you use Microsoft 365 and want an AI agent that:

- doesn't ship your inbox to a third-party SaaS,
- gates every action through a policy you can read,
- redacts PII and credentials from outbound text,
- works in 60 seconds from `pip install`,

then ersan is for you.

## Architecture

ersan is **the gate** (owns the user relationship), not **infrastructure**
(consumed by other agents). Capabilities load as **skills**, packaged into
**plugins**.

Three pillars:

- **Core**: pydantic-ai Agent runtime, CLI, REPL
- **Policy**: trust tiers (`ask_first`, `do_and_tell`, `do_it`) gating every tool call
- **Shield**: PII / credential redaction on outbound text

(Microsoft Graph OAuth via MSAL ships in v0.4.0 alongside the inbox skills
that need it; see Roadmap below.)

In the current runtime, ersan's core is `pydantic_ai.Agent`. Tool selection
is LLM-driven from natural-language prompts, `ersan.policy` enforces
tier-based gating via `PolicyCapability.wrap_tool_execute()`, and
`ersan.shield` enforces pattern-based blocking plus redaction via
`ShieldHook` registered on the `tool:pre` event of
`ersan.hooks.HookRegistry`, fired by `HookBridgeCapability`.

## Privacy

- **No telemetry.** Zero phone-home.
- **No third-party LLM calls** unless your config calls them.
  At v0.2.0 this is structurally enforced: local-provider client construction is
  covered by `tests/integration/test_local_provider_no_network.py`, which proves
  the provider factories make zero outbound requests during construction.
- **Your tokens stay local** in `~/.ersan/`, file-permissions-restricted
  (POSIX `0600` / Windows ACL via `icacls`). OS keyring integration is
  planned for a later release; the file-only path is the supported
  default and works on every supported OS including headless Linux.
- **Audit-log to your own sink** (`~/.ersan/audit.log`).

## Platform support

ersan is platform-agnostic by construction (per Constitution §Cross-platform invariants).
Every PR runs against:

- **Per PR (6 jobs)**: `ubuntu-latest` × Python 3.10 / 3.11 / 3.12 / 3.13;
  `windows-latest` × Python 3.13; `macos-latest` × Python 3.13.
- **Weekly cron (12 jobs)**: full cartesian — every supported OS × every
  supported Python version.
- **On every release tag (6 jobs)**: smoke-install matrix —
  `{ubuntu, windows, macos} × {Python 3.10, 3.13}` runs `pip install`
  against the freshly built wheel before it reaches PyPI via Trusted
  Publishing with Sigstore PEP 740 attestations.

A wheel does not reach PyPI until the smoke-install matrix passes on all
three operating systems.

## Roadmap

| Version | Status | Goal |
|---|---|---|
| **v0.1.x** | ✅ released | Architecture-complete: foundations + eval harness + skill loader |
| **v0.2.x** | ✅ released | Model Provider Abstraction — `ersan.providers`, local-first Ollama config, Anthropic config, privacy-invariant provider tests |
| **v0.3.0** | ✅ released | Constitutional pillars — bundled slim port of `ersan.policy` + `ersan.shield`, wired into the loader with the default retail `ask_first` policy and `~/.ersan/audit.log` audit path |
| **v0.4.0** | next | Agent runtime adoption — `pydantic_ai.Agent`, `PolicyCapability`, `HookBridgeCapability`, slim REPL + one-shot CLI |
| **v0.5.0** | planned | Inbox MVP — Outlook toolset + Microsoft Graph token storage and MSAL device-code flow |

## Configuration

Local Ollama example:

```yaml
llm:
  provider: ollama
  model: llama3
  base_url: http://localhost:11434/v1
```

Anthropic example:

```yaml
llm:
  provider: anthropic
  model: claude-3-5-sonnet-latest
  api_key: ${ANTHROPIC_API_KEY}
```

v0.2.0 reads `ANTHROPIC_API_KEY` only. The source codebase's
`~/.claude/.credentials.json` fallback is not yet ported.

Run `ersan config` to see what the runtime resolved from your env. See
[docs/configuration.md](docs/configuration.md) for the schema-backed env surface.

## How ersan is built

ersan is maintained by Ersan Bilik with AI coding assistants coordinated
through GitHub Spec-Kit. Every release ships through the same cycle:
spec → plan → implementation → cross-review → merge → release.

## Get involved

- 🐛 [Issues](https://github.com/ersan-ai/ersan/issues)
- 📜 [Constitution](CONSTITUTION.md) — what ersan is and isn't
- 🤝 [Contributing](CONTRIBUTING.md)
- 🔒 [Security disclosure](SECURITY.md)
- 📜 [Code of Conduct](CODE_OF_CONDUCT.md)

## License

Apache 2.0. See [LICENSE](LICENSE).

Built by [Ersan Bilik](https://github.com/bilersan).
