Metadata-Version: 2.3
Name: agentinterface
Version: 1.0.0
Summary: Agent GUIs
License: MIT
Keywords: ai,agents,interface,ui,components,protocol,selection,rendering,react,conversational,aip,magic
Author: Tyson Chan
Author-email: tyson.chan@proton.me
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: all
Provides-Extra: anthropic
Provides-Extra: gemini
Provides-Extra: openai
Requires-Dist: anthropic (>=0.20.0) ; extra == "all"
Requires-Dist: anthropic (>=0.20.0) ; extra == "anthropic"
Requires-Dist: google-genai (>=1.29.0) ; extra == "all"
Requires-Dist: google-genai (>=1.29.0) ; extra == "gemini"
Requires-Dist: google-genai (>=1.36.0,<2.0.0)
Requires-Dist: openai (>=1.0) ; extra == "all"
Requires-Dist: openai (>=1.0) ; extra == "openai"
Requires-Dist: typing-extensions (>=4.0)
Description-Content-Type: text/markdown

# AgentInterface

**Agents shape UI. Not templates.**

Agent GUIs without ceremony.

```bash
pip install agentinterface
```

## Pattern

```
Agent text → Shaper LLM → Component JSON → React UI
```

Wrap any agent. Any LLM selects components. React renders UI.

## Usage

```python
from agentinterface import ai

def sales_agent(query: str) -> str:
    return "Q3 revenue: $2M, up 15%. Users: 10K."

enhanced = ai(sales_agent, llm="gemini")
text, components = await enhanced("Show Q3 dashboard")

# Returns:
# text: "Q3 revenue: $2M, up 15%. Users: 10K."
# components: [{"type": "card", "data": {"title": "Q3 Revenue", "value": "$2M"}}]
```

Works with sync, async, streaming agents.

## LLM Providers

```python
# String providers (defaults: gpt-4.1-mini, gemini-2.5-flash, claude-4.5-sonnet-latest)
ai(agent, llm="openai")
ai(agent, llm="gemini")
ai(agent, llm="anthropic")

# Custom models
from agentinterface.llms import OpenAI, Gemini, Anthropic
ai(agent, llm=OpenAI(model="gpt-4o"))
ai(agent, llm=Gemini(model="gemini-pro"))

# Custom LLM
from agentinterface.llms import LLM

class CustomLLM(LLM):
    async def generate(self, prompt: str) -> str:
        ...

ai(agent, llm=CustomLLM())
```

## Composition

```python
# Vertical stack
[card1, card2, card3]

# Horizontal grid
[[card1, card2, card3]]

# Mixed layout
[
  card1,              # Full width
  [card2, card3],     # Side by side
  table1              # Full width
]
```

Nested arrays = horizontal. Arrays = vertical.

## Bidirectional Callbacks

```python
from agentinterface.callback import Http

callback = Http()
enhanced = ai(agent, llm="gemini", callback=callback)

async for event in enhanced("Show sales dashboard"):
    if event["type"] == "component":
        components = event["data"]["components"]
        
        # User clicks → callback receives interaction
        interaction = await callback.await_interaction(timeout=300)
        
        # Agent continues based on interaction
```

Components talk back to agent. Conversational UI.

## Custom Components

Create React component with metadata:

```tsx
// src/ai/metric.tsx
export const Metric = ({ label, value, change }) => (
  <div>
    <span>{label}</span>
    <strong>{value}</strong>
    <span>{change}</span>
  </div>
);

export const metadata = {
  type: 'metric',
  description: 'Key performance metric with change indicator',
  schema: {
    type: 'object',
    properties: {
      label: { type: 'string' },
      value: { type: 'string' },
      change: { type: 'string', optional: true }
    },
    required: ['label', 'value']
  },
  category: 'content'
};
```

Run autodiscovery:

```bash
npx agentinterface discover
```

Component automatically available to shaper LLM.

## Built-in Components

10 components: `card` `table` `timeline` `accordion` `tabs` `markdown` `image` `embed` `citation` `suggestions`

## API

```python
ai(agent, llm, components=None, callback=None, timeout=300)
protocol(components=None)
shape(text, context, llm)
```

## Docs

Full documentation: [github.com/iteebz/agentinterface](https://github.com/iteebz/agentinterface)

## License

MIT