ersan 0.3.1

Open-source AI agent for Microsoft 365.

 ███████╗██████╗ ███████╗ █████╗ ███╗   ██╗
 ██╔════╝██╔══██╗██╔════╝██╔══██╗████╗  ██║
 █████╗  ██████╔╝███████╗███████║██╔██╗ ██║
 ██╔══╝  ██╔══██╗╚════██║██╔══██║██║╚██╗██║
 ███████╗██║  ██║███████║██║  ██║██║ ╚████║
 ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝

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: skill loader, CLI, REPL
• Policy: trust tiers (ask_first, do_and_tell, do_it) gating every skill 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.)

As of v0.3.0, the loader defaults enforce the two gate modules directly: every skill call goes through ersan.policy.PolicyEngine.evaluate() before execution, and every string result goes through ersan.shield.ContentShield.scan() before it reaches the caller.

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	Inbox MVP — inbox.list_unread, inbox.summarize, inbox.draft_reply on top of ersan.providers, plus the source-faithful Microsoft Graph token store and MSAL auth

Configuration

Local Ollama example:

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

Anthropic example:

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.

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
• 📜 Constitution — what ersan is and isn't
• 🤝 Contributing
• 🔒 Security disclosure
• 📜 Code of Conduct

License

Apache 2.0. See LICENSE.

Built by Ersan Bilik.