Metadata-Version: 2.4
Name: persona-core
Version: 0.1.0
Summary: Build AI personas with typed memory and tier-routed model selection.
Project-URL: Homepage, https://github.com/yasinhessnawi1/Open-Persona
Project-URL: Repository, https://github.com/yasinhessnawi1/Open-Persona
Project-URL: Issues, https://github.com/yasinhessnawi1/Open-Persona/issues
Project-URL: Changelog, https://github.com/yasinhessnawi1/Open-Persona/blob/main/CHANGELOG.md
Author-email: Yasin Hessnawi <yasinhessnawi1@gmail.com>
License-Expression: PolyForm-Noncommercial-1.0.0
License-File: LICENSE
Keywords: agent,agentic,ai,llm,persona,pgvector,rag,typed-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.30
Requires-Dist: chromadb<2,>=1.0
Requires-Dist: fal-client<2,>=1.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: loguru<1,>=0.7
Requires-Dist: mcp<2,>=1.0
Requires-Dist: openai<2,>=1.30
Requires-Dist: pydantic-settings<3,>=2.3
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: python-jose[cryptography]<4,>=3.3
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: regex<2027,>=2024.0
Requires-Dist: sentence-transformers<4,>=3.0
Requires-Dist: tiktoken<1,>=0.7
Requires-Dist: trafilatura<3,>=2.0
Requires-Dist: typer<1,>=0.12
Provides-Extra: local
Requires-Dist: accelerate<1,>=0.31; extra == 'local'
Requires-Dist: bitsandbytes<1,>=0.43; extra == 'local'
Requires-Dist: torch<3,>=2.3; extra == 'local'
Requires-Dist: transformers<5,>=4.42; extra == 'local'
Provides-Extra: postgres
Requires-Dist: pgvector<1,>=0.3; extra == 'postgres'
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'postgres'
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'postgres'
Provides-Extra: sandbox
Requires-Dist: docker<8,>=7; extra == 'sandbox'
Provides-Extra: test
Requires-Dist: pypdf<7,>=6.0; extra == 'test'
Description-Content-Type: text/markdown

# persona-core

> Source-available Python library for building AI personas with typed memory
> and tier-routed model selection. Noncommercial use only.

**Status:** PolyForm Noncommercial 1.0.0 · Source Available (Noncommercial Use Only)

## What it is

`persona-core` lets you author a persona as a single YAML document (identity,
constraints, self-facts, worldview claims with epistemic tags, tools, skills)
and run it against any of seven model providers — Anthropic, OpenAI, DeepSeek,
Groq, Together, NVIDIA, OpenRouter, local Ollama, or local HF — with four
typed memory stores (identity, self-facts, worldview, episodic) backed by
ChromaDB or Postgres + pgvector. Ships the schema, the four memory stores
behind a `MemoryStore` protocol, the backend layer behind a `ChatBackend`
protocol, a sandboxed tool layer (`Toolbox`, MCP client, built-in
`web_search` / `web_fetch` / `file_read` / `file_write`), a skills layer
(`SkillScanner` + `SkillInjector` + six built-in skill packs), a vision
layer (`ImageContent` + `ImageBackend`), document ingestion + generation,
a code-execution sandbox protocol, an `AuditLogger` protocol with a JSONL
default, per-component loguru logging, and a `persona` CLI. Every other
Open Persona package depends on this one; this one depends on nothing inside
Open Persona.

## Install

```bash
pip install persona-core                 # core + Chroma + frontier SDKs
pip install persona-core[local]          # adds torch / transformers for local HF inference
pip install persona-core[postgres]       # adds psycopg + pgvector for the Postgres backend
pip install persona-core[sandbox]        # adds docker SDK for LocalDockerSandbox
```

Python ≥ 3.11.

For workspace development from the monorepo:

```bash
git clone https://github.com/yasinhessnawi1/Open-Persona.git
cd open-persona
uv sync --all-packages
```

## Run

Author and chat with a persona from the terminal:

```bash
persona init                                      # interactive → astrid.yaml
persona validate examples/astrid_tenancy_law.yaml
export PERSONA_PROVIDER=deepseek
export PERSONA_MODEL=deepseek-chat
export PERSONA_API_KEY=<your-key>
persona chat examples/astrid_tenancy_law.yaml
persona audit examples/astrid_tenancy_law.yaml    # tail the JSONL audit log
```

Three example personas ship in [`examples/`](examples/):
`astrid_tenancy_law.yaml` (Norwegian tenancy-law assistant),
`kai_research.yaml` (research assistant), `maren_writing_coach.yaml`
(tool-free writing coach).

Programmatic use:

```python
import asyncio
from pathlib import Path

from persona.schema.persona import Persona
from persona.backends import OpenAICompatibleBackend, BackendConfig
from persona.schema.conversation import ConversationMessage

async def main() -> None:
    persona = Persona.from_yaml(Path("examples/astrid_tenancy_law.yaml"))
    backend = OpenAICompatibleBackend(
        BackendConfig(provider="deepseek", model="deepseek-chat")
    )
    system = f"You are {persona.identity.name}, {persona.identity.role}."
    reply = await backend.chat([
        ConversationMessage(role="system", content=system, created_at=None),
        ConversationMessage(role="user", content="Hva sier husleieloven om mugg?", created_at=None),
    ])
    print(reply.content)

asyncio.run(main())
```

For the full conversation loop with router, tool dispatch, episodic
write-back and per-turn logging, compose with `persona-runtime`.

## Test

```bash
uv run pytest packages/core                          # unit + contract (default)
uv run pytest packages/core -m integration           # needs Postgres in Docker
uv run mypy packages/core/src --strict
uv run ruff check packages/core
```

## Highlights

- Frozen Pydantic v2 boundary models, `extra="forbid"` everywhere
- Deterministic chunk IDs: `{persona_id}::{store_kind}::{index:04d}`
- Versioned append-only stores; identity is immutable at runtime
- SHA-256 `content_hash` on every chunk; one `AuditEvent` per mutation
- Three-source write policy: `system` / `user` / `persona_self`
- 2k-token-budgeted skill injection (`SkillInjector.TOKEN_BUDGET`)
- Native tool calls (Anthropic / OpenAI / DeepSeek / Groq / Together / NVIDIA /
  OpenRouter) + prompt-shim fallback (Ollama / HF local)
- MCP Streamable HTTP client + adapter
- Sandboxed file tools (path resolver rejects `..`, abs paths, symlink
  escape, NUL bytes, mixed separators)
- Six built-in skill packs: `web_research`, `document_drafting`,
  `docx_generation`, `pptx_generation`, `xlsx_generation`, `pdf_generation`
- Image generation backends (OpenAI gpt-image-1, fal.ai Flux 1.1 [pro])
  with three-layer safety + categorical hard-line filter
- Vision input (`ImageContent`) + document ingestion + a `CodeSandbox`
  protocol with `LocalDockerSandbox` reference implementation

## Architecture role

`persona-core` is layer 4 of the Open Persona stack — the source-available
foundation. A persona is a YAML document; the schema, the typed memory
stores, the model-provider adapters, and the tool/skill machinery all live
here. `persona-runtime` composes the orchestration loop on top of this
library; `persona-api` exposes it over HTTP; `persona-web` is the browser
front-end. The dependency arrow points one way — `persona-core` imports
nothing from the upper layers.

## Contribute

Contributions welcome under the same PolyForm Noncommercial 1.0.0 license.
The package is source-available for noncommercial use; commercial use
requires a separate license — contact the rights holder. Issues and pull
requests welcome at
[github.com/yasinhessnawi1/Open-Persona](https://github.com/yasinhessnawi1/Open-Persona).
See [LICENSE](LICENSE) and the package
[`SPEC.md`](SPEC.md) for the public surface.
