Metadata-Version: 2.4
Name: chester-ai
Version: 0.1.4
Summary: Python SDK for the Chester AI agent platform
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: googleapis-common-protos
Requires-Dist: grpcio>=1.60
Requires-Dist: protobuf>=4.25
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# chester-ai

Python SDK for the Chester AI agent platform. Build a consulting firm on an API.

## Install

```bash
pip install chester-ai
# or
uv add chester-ai
```

## Quick Start

The high-level API uses consulting language that matches [chester.ai](https://chester.ai):

```python
from chester_ai import Chester, Step, Gate, PricingRule

chester = Chester(url="localhost:8990", api_key="cht_your_api_key_here")

# Deploy consultants
analyst = chester.consultant("market-analyst",
    identity="You are a market sizing specialist.",
    model="claude-sonnet-4-20250514")

researcher = chester.consultant("researcher",
    identity="You are a research analyst.",
    model="claude-sonnet-4-20250514")

# Brief a consultant (async task)
task_id = analyst.brief("Estimate the TAM for AI consulting in 2026")

# Stream a conversation
for text in analyst.chat("What methodology do you use for market sizing?"):
    print(text, end="")

# Persistent memory
analyst.remember("Client prefers conservative estimates with 95% confidence intervals")
print(analyst.recall())
```

## Practice Groups (Teams)

```python
# Create a due diligence practice
practice = chester.practice("dd-practice",
    coordinator="dd-lead",
    members=["market-analyst", "fin-analyst", "legal-reviewer"])

# Run an engagement
result = practice.run("Conduct due diligence on TargetCo — $500M acquisition")

# Shared practice memory
practice.memory = "This practice focuses on tech M&A in the $100M-$1B range"
```

## Client Models (Digital Twins)

```python
# Define a client model type
type_id = chester.client_model_type("enterprise-client",
    description="Fortune 500 client model",
    base_agent="analyst")

# Create a persistent client model
acme = chester.client_model("Acme Corp",
    type_id=type_id,
    external_id="crm-12345")

# Feed it knowledge
acme.learn("engagement_start", '{"deal_size": "500M", "sector": "tech"}')

# Query the model
answer = acme.query("What is this client's risk appetite?")
```

## Project Boards (Kanban)

```python
board = chester.board("acme-dd-pipeline", description="Due diligence tracker")
board.add_card("Market Sizing", agent_name="market-analyst")
board.add_card("Financial Model", agent_name="fin-analyst")
board.execute()  # agents start working
```

## Objectives (Cognitive Goals)

```python
obj = chester.objective("market-analyst",
    "Complete market sizing for Acme deal",
    budget_usd=5.0,
    acceptance_criteria="TAM/SAM/SOM with confidence intervals")

# The agent works autonomously, escalating when it needs human input
for esc in obj.escalations:
    obj.resolve_escalation(esc.id, "Proceed with conservative estimate")
```

## Outcome Pricing

```python
# Compose pricing rules
chester.pricing_rule(PricingRule(
    dimension="deliverable", rate=2500.0,
    entity_name="market-analyst", notes="Per market sizing report"))

chester.pricing_rule(PricingRule(
    dimension="month", rate=8000.0,
    notes="Monthly retainer for ongoing advisory"))

# Check margins
report = chester.margin_report(days=30)

# Generate invoice
chester.generate_invoice("2026-04")
```

## Engagement Workflows

```python
# Define a reusable engagement template
template_id = chester.engagement("due-diligence-flow",
    description="Full commercial DD workflow",
    steps=[
        Step(instruction="Market sizing analysis", agent="market-analyst"),
        Step(instruction="Financial model review", agent="fin-analyst"),
        Gate(name="partner-review"),  # human approval
        Step(instruction="Risk assessment", agent="legal-reviewer"),
        Step(instruction="Executive summary", agent="dd-lead"),
        Gate(name="client-delivery"),
    ])

# Run it
chester.run_engagement(template_id, entity_id="acme-corp")
```

## Human-in-the-Loop

```python
# Review pending decisions across all consultants
for decision in chester.pending_decisions():
    print(f"{decision.agent}: {decision.question}")
    chester.decide(decision.decision_id, "Approved")
```

## Raw gRPC Access

The full 27-service gRPC API is available as an escape hatch:

```python
# Via the Chester high-level client
chester.rpc.agents.ListAgents(proto.ListAgentsRequest())
chester.rpc.queue.SendTask(proto.SendTaskRequest(agent="bot", message="hello"))

# Or directly
from chester_ai import ChesterClient, proto
client = ChesterClient(url="localhost:8990", api_key="cht_...")
client.agents.ListAgents(proto.ListAgentsRequest())
```

## Requirements

- Python 3.10+
- Chester daemon running (default port 8990)
