Metadata-Version: 2.4
Name: persona-agent
Version: 0.1.0
Summary: PersonaAgent: a configurable, persona-based LLM agent wrapper with memory, skills, and adaptive behavior.
Author: littledumb
Author-email: littledumb <littledumb@dumbsmart.org>
License-Expression: MIT
Requires-Dist: litellm>=1.80.7
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/dumbsmart-org/persona-agent
Project-URL: Issues, https://github.com/dumbsmart-org/persona-agent/issues
Project-URL: Repository, https://github.com/dumbsmart-org/persona-agent.git
Description-Content-Type: text/markdown

# PersonaAgent

**PersonaAgent** is a Python library for building **persona-based LLM agents** - agents that:

- Are instantiated with different **personalities, styles, and skills**
- Maintain **memory** of past interactions
- Can be wired to any **LLM backend** (OpenAI, Anthropics, etc.)
- Are easy to compose into **multi-agent systems**

> Concept: a *PersonaAgent* is "a configurable, persona-based LLM agent that can be instantiated with different skills and styles and that adapts based on its past interactions."

## Features

- **Persona profiles** - define personality, style, goals, domain, etc.
- **Memory** - simple interaction history + extensible hooks for long-term memory.
- **Skills** - plug in Python functions the agent can call.
- **Model-agnostic** - you pass in how to call your LLM.
- **Composable** - use multiple PersonaAgents in the same app.

## Installation

```bash
pip install persona-agent
```

## Quickstart

```python
from persona_agent import PersonaAgent, DOCTOR_PROFILE

# 1. Define how to call your model
def dummy_model(prompt: str, **kwargs) -> str:
  # Replace this with a real LLM call
  return f"(Model responding to): {prompt[:80]}..."

# 2. Instantiate a PersonaAgent
agent = PersonaAgent(
  name="Dr. Maple",
  model=dummy_model,
  persona=DOCTOR_PROFILE,
)

# 3. Interact
response = agent.react("What are common symptoms of generalized myasthenia gravis?")
print(response)
```

## Persona definition

A persona is just a Python `dict`:

```python
doctor_persona = {
  "role": "neurologist",
  "personality": "calm, analytical, empathetic",
  "style": "concise, medically accurate, patient-friendly",
  "goals": [
    "educate patients safely",
    "avoid providing diagnosis",
    "encourage consultation with physicians",
  ],
  "domain": "neurology, autoimmune diseases",
}
```

You can load predefined ones from persona_agent.profiles.

## Skills

You can attach Python functions as skills:

```python
def search_literature(query: str) -> str:
  # Stub: connect to your own system
  return f"Search result for: {query}"

agent.add_skill("search_literature", search_literature)

# Then call inside your app:
result = agent.call_skill("search_literature", "efgartigimod gMG phase 3")
print(result)
```

Agent logic itself is up to you: PersonaAgent provides the structure and hooks.

## Memory

By default, PersonaAgent keeps a simple in-memory history of interactions:

```python
agent.react("Hello!")
agent.react("Tell me a joke about neurons.")
print(agent.memory.recent(5))
```

You can also plug in your own memory backend (e.g., vector DB, file, Redis) by subclassing `Memory`.

## Project structure

```text
src/persona_agent/
    core.py      # PersonaAgent main class
    memory.py    # Memory abstractions
    skills.py    # Skill registry and helpers
    profiles.py  # Predefined persona profiles
    models.py    # Model adapter types / helpers
```

## Roadmap

- [ ] Built-in LLM adapters (via [`litellm`](https://github.com/BerriAI/litellm))
- [ ] Vector-based long-term memory
- [ ] Configuration of persona specs
- [ ] Multi-agent interactions (follow [MCP](https://modelcontextprotocol.io/docs/getting-started/intro)?)

## Contributing

1. Fork this repo
2. Create a branch: `git checkout -b feature/my-feature`
3. Run tests: pytest
4. Open a Pull Request 🎉

## License

This project is licensed under the MIT license.
