Metadata-Version: 2.4
Name: identa-agent
Version: 0.0.1
Summary: The identity layer for AI agents — export, persist, and migrate agent personas across any LLM provider.
Project-URL: Homepage, https://github.com/shepax/identa-agent
Project-URL: Repository, https://github.com/shepax/identa-agent
Project-URL: Issues, https://github.com/shepax/identa-agent/issues
Author-email: shepax <your@email.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,anthropic,identity,llm,openai,persona
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Identa Agent

**Your AI agent loses its soul every time you switch models. Identa Agent fixes that.**

The agentic economy needs an identity layer. Identa Agent is the open-source middleware that decouples *who your agent is* from *what model it runs on*. Define your agent's persona, memory, and behavioral DNA in a portable APF file. Migrate across providers in one command. Build agents that outlive any single model generation.

[![License: Apache 2.0 + Commons Clause](https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-blue.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/identa-agent.svg)](https://pypi.org/project/identa-agent/)
[![Discord](https://img.shields.io/discord/identa-agent?label=community)](https://discord.gg/identa-agent)
[![GitHub stars](https://img.shields.io/github/stars/shepax/identa-agent)](https://github.com/shepax/identa-agent/stargazers)

---

## The problem

Every time you upgrade your LLM or switch providers, your agent loses its personality, memory, and brand voice. You start over. Again.

- Migrating from GPT-4o to Claude? **Rebuild your system prompt from scratch.**
- Upgrading to the next model generation? **Drift happens silently.**
- Scaling across a team? **No standard way to version or share agent identity.**

There is no passport for AI agents. Until now.

---

## What Identa Agent does

Identa Agent introduces the **Agent Persona Format (APF)** — an open, provider-agnostic standard for encoding everything that makes an agent *itself*: its voice, its memory, its behavioral rules, and its provider-specific configurations.

```bash
pip install identa-agent
```

### Export an agent identity
```bash
identa-agent export --provider openai --agent-id my-agent --output aria.apf.json
```

### Migrate to a new provider in one command
```bash
identa-agent import --provider anthropic --file aria.apf.json
```

### Your agent. Same soul. Different brain.

---

## Core features

### Export / Import across providers
Serialize your agent's full identity — tone, behavioral rules, memory state, and instructions — into a portable APF file. Import it into any supported provider with automatic prompt translation.

### Memory persistence layer
Identa Agent maintains episodic memory (what your agent has done) and procedural memory (how your agent behaves) across sessions, model switches, and upgrades. Your agent remembers who it is.

### Identa Agent CLI
A developer-first command line interface to initialize, export, import, inspect, and diff agent identities. Works standalone or integrated into your CI/CD pipeline.

```bash
identa-agent init                          # scaffold a new agent identity
identa-agent export --provider openai      # export current agent to APF
identa-agent import --provider anthropic   # import APF into new provider
identa-agent diff aria-v1.apf.json aria-v2.apf.json  # inspect what changed
identa-agent validate aria.apf.json        # validate against APF spec
```

---

## Supported providers

| Provider | Export | Import | Status |
|---|---|---|---|
| OpenAI (GPT-4o, GPT-4.1) | 🔜 | 🔜 | Planned |
| Anthropic (Claude Sonnet, Opus) | 🔜 | 🔜 | Planned |
| Google Gemini | 🔜 | 🔜 | Planned |
| Ollama / local models | 🔜 | 🔜 | Planned |

---

## Quick start

### 1. Install
```bash
pip install identa-agent
```

### 2. Initialize a new agent identity
```bash
identa-agent init --name "Aria" --role "Customer success agent"
```

This creates an `aria.apf.json` file in your working directory.

### 3. Connect to a provider and export
```bash
export OPENAI_API_KEY=sk-...
identa-agent export --provider openai --agent-id asst_xxx --output aria.apf.json
```

### 4. Import into a new provider
```bash
export ANTHROPIC_API_KEY=sk-ant-...
identa-agent import --provider anthropic --file aria.apf.json
```

### 5. Use in Python
```python
from identa-agent import IdentaAgent

agent = IdentaAgent.from_file("aria.apf.json")
response = agent.run("Hello, I need help with my order.")
print(response)
```

---

## The APF format

The Agent Persona Format is an open JSON standard. Here's what an APF file looks like:

```json
{
  "identa_version": "0.1",
  "metadata": {
    "name": "Aria",
    "role": "Customer success agent",
    "created_at": "2026-03-19T00:00:00Z",
    "version": "1.0.0"
  },
  "identity": {
    "tone": ["warm", "concise", "professional"],
    "avoid": ["filler phrases", "excessive apologies", "jargon"],
    "core_traits": ["empathetic", "solution-focused", "brand-consistent"]
  },
  "memory": {
    "episodic": [],
    "procedural": {
      "escalation_threshold": "user expresses frustration twice",
      "response_length": "concise, max 3 sentences unless instructed"
    }
  },
  "provider_adapters": {
    "openai": {
      "model": "gpt-4o",
      "system_prompt_template": "..."
    },
    "anthropic": {
      "model": "claude-sonnet-4-6",
      "system_prompt_template": "..."
    }
  }
}
```

Full spec: [SPEC.md](SPEC.md) | RFC discussion: [#1](https://github.com/shepax/identa-agent/issues/1)

---

## Project structure

```
identa-agent/
├── identa_agent/
│   ├── cli.py                  # CLI entry point
│   ├── core/
│   │   ├── schema.py           # APF schema validation
│   │   ├── memory.py           # Memory persistence layer
│   │   └── adapters/
│   │       ├── base.py         # Abstract adapter interface
│   │       ├── openai.py       # OpenAI adapter
│   │       └── anthropic.py    # Anthropic adapter
├── examples/
│   ├── customer_service/       # Example: customer success agent
│   └── sales_assistant/        # Example: outbound sales agent
├── tests/
├── SPEC.md                     # APF format specification
├── RFC.md                      # Open RFC for community input
└── CONTRIBUTING.md
```

---

## Roadmap

### v0.1 — Foundation *(current)*
- [x] APF schema definition
- [ ] OpenAI adapter (export + import)
- [ ] Anthropic adapter (export + import)
- [ ] Core CLI (`init`, `export`, `import`, `validate`)
- [ ] Memory persistence layer (episodic + procedural)

### v0.2 — Developer experience
- [ ] `identa-agent diff` — inspect persona changes between versions
- [ ] LangChain integration
- [ ] LangGraph integration
- [ ] Example agents library

### v0.3 — Ecosystem
- [ ] Google Gemini adapter
- [ ] Ollama / local model support
- [ ] APF registry (community-shared personas)

---

## Contributing

Identa Agent is built in public. We want your fingerprints on the spec.

The best place to start is the **[RFC issue #1](https://github.com/shepax/identa-agent/issues/1)** — the open debate on what the APF format should look like. Every opinion matters at this stage.

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to submit adapters for new providers.

---

## License

Identa Agent is released under the **Apache 2.0 License with Commons Clause**.

You are free to use, modify, and distribute Identa Agent — including in commercial products you build *with* Identa. The Commons Clause restriction applies only to selling Identa Agent itself as a hosted service or commercial offering.

See [LICENSE](LICENSE) for the full text.

---

## Why we're building this

The agentic economy is arriving fast. Enterprises are deploying long-horizon AI agents that carry real brand identity and customer relationships. But every model upgrade, every provider switch, every infrastructure change risks erasing what makes those agents valuable.

We believe agent identity should be portable, versionable, and provider-agnostic — just like your code.

Identa Agent is the layer that makes that possible.

---

*Built in public. Shaped by the community.*
*Star the repo if you believe agent identity matters.*
