ersan 0.5.0

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: 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:

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.

Run ersan config to see what the runtime resolved from your env. See 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
• 📜 Constitution — what ersan is and isn't
• 🤝 Contributing
• 🔒 Security disclosure
• 📜 Code of Conduct

License

Apache 2.0. See LICENSE.

Built by Ersan Bilik.